en-US/RemoteWrench.dll-Help.xml
|
<?xml version="1.0" encoding="utf-8"?> <helpItems xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" schema="maml" xmlns="http://msh"> <command:command> <command:details> <command:name>ConvertTo-PSRPPacket</command:name> <maml:description> <maml:para>Converts PSRP Out of Process protocol strings into parsed packet objects.</maml:para> </maml:description> <command:verb>ConvertTo</command:verb> <command:noun>PSRPPacket</command:noun> </command:details> <maml:description> <maml:para>The `ConvertTo-PSRPPacket` cmdlet parses PowerShell Remoting Protocol (PSRP) packet strings into structured `OutOfProcPacket` objects. These packets are typically captured from PowerShell remoting sessions and contain XML-formatted protocol data. The cmdlet handles fragmented messages by maintaining state across multiple packets and reassembling them into complete PSRP messages. This is useful for analyzing PowerShell remoting traffic and debugging remote session communication.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>ConvertTo-PSRPPacket</maml:name> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="0" aliases="none"> <maml:name>InputObject</maml:name> <maml:description /> <command:parameterValue required="true" variableLength="false">string[]</command:parameterValue> <dev:type> <maml:name>System.String[]</maml:name> </dev:type> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="true (ByValue)" position="0" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>The PSRP packet strings to parse. Each string should be a complete XML packet from the PowerShell Remoting Protocol. Empty or whitespace-only lines are automatically skipped.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">System.String[]</command:parameterValue> <dev:type> <maml:name>System.String[]</maml:name> </dev:type> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>System.String[]</maml:name> </dev:type> <maml:description> <maml:para>PSRP packet strings in XML format. The cmdlet accepts pipeline input and processes each line.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>RemoteWrench.OutOfProcPacket</maml:name> </dev:type> <maml:description> <maml:para>Parsed PSRP packet objects containing the packet type, GUID, stream information, fragments, and decoded messages.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para>- Invalid packets generate non-terminating errors and are skipped - Fragment state persists for the lifetime of the cmdlet execution - A message split across multiple fragments is only output once its end fragment is received, a fragment that is received without its start fragment or out of order generates an error - Fragments are reassembled per `PSGuid` and object id, object ids are only unique within the process that sent them so input from multiple sessions should be passed to separate `ConvertTo-PSRPPacket` calls</maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>--------- Example 1: Parse PSRP packets from a log file ---------</maml:title> <maml:introduction> <maml:para>```powershell Get-Content psremoting.log | ConvertTo-PSRPPacket ```</maml:para> <maml:para>€</maml:para> <maml:para>Reads PSRP packet strings from a log file and converts them into parsed packet objects.</maml:para> </maml:introduction> <dev:code /> <dev:remarks /> </command:example> <command:example> <maml:title>--------- Example 2: Parse and format PSRP packets ---------</maml:title> <maml:introduction> <maml:para>```powershell Get-Content psremoting.log | ConvertTo-PSRPPacket | Format-PSRPPacket ```</maml:para> <maml:para>€</maml:para> <maml:para>Parses PSRP packets and formats them into human-readable output with color coding.</maml:para> </maml:introduction> <dev:code /> <dev:remarks /> </command:example> </command:examples> <command:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version</maml:linkText> <maml:uri>https://www.github.com/jborean93/PowerShell-RemoteWrench/blob/main/docs/en-US/RemoteWrench/ConvertTo-PSRPPacket.md</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Format-PSRPPacket</maml:linkText> <maml:uri>./Format-PSRPPacket.md</maml:uri> </maml:navigationLink> </command:relatedLinks> </command:command> <command:command> <command:details> <command:name>Format-PSRPPacket</command:name> <maml:description> <maml:para>Formats PSRP packet objects into human-readable output.</maml:para> </maml:description> <command:verb>Format</command:verb> <command:noun>PSRPPacket</command:noun> </command:details> <maml:description> <maml:para>The `Format-PSRPPacket` cmdlet formats parsed PSRP (PowerShell Remoting Protocol) packet objects from `ConvertTo-PSRPPacket` into human-readable text. Each message is decoded into a summary and the fields that matter for its type, for example the command line of a `CreatePipeline`, the state and error of a `PipelineState`, or the method and arguments of a host call. `SecureString` values are always shown as `[SecureString]`, even when the transport sends them unencrypted. The `-View` parameter selects how the packets are laid out, each view answers a different question: - `Timeline`: what was actually sent over the transport. This is the default and shows every packet in the order it was received, one line for each message, fragment, and control packet like `Command` or `DataAck`. The columns are the packet number, direction, packet type, PSGuid, message type, object and fragment id, message size, and a summary of the message. Use it to analyse the raw exchange, for example to find a missing acknowledgement, see how a large object was fragmented, or match a packet number from another view. The PSGuid and size columns are dropped when the output is narrower than 110 characters. - `Grouped`: what happened in the session. Each PSRP message is a single line under the runspace pool and pipeline it belongs to, so a pipeline reads as its command, the output and records it produced, and the state it finished in. Acknowledgements, `Command` packets, and fragments are left out. When pipelines run concurrently a new header marked `(continued)` is written each time the messages switch between them, so the messages stay in the order received. - `GroupedDetail`: `Grouped` with the in-depth information of each message underneath it. The packet number, packet type, and fragment of every fragment the message was received in, the decoded fields, like the parameters of a host call or the full multi-line script of a `CreatePipeline`, and object data as a tree. Use it to investigate a specific message found in the other views. Every view streams, a packet is output as soon as it is received, so the cmdlet can follow a log that is still being written with `Get-Content -Wait`. The direction is shown as `C→S` or `▶` for a packet sent by the client and `S→C` or `◀` for one sent by the server. The output uses ANSI color codes by default, with different colors for each direction and red for errors.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Format-PSRPPacket</maml:name> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Packet</maml:name> <maml:description /> <command:parameterValue required="true" variableLength="false">OutOfProcPacket[]</command:parameterValue> <dev:type> <maml:name>RemoteWrench.OutOfProcPacket[]</maml:name> </dev:type> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>NoColor</maml:name> <maml:description /> <dev:type> <maml:name>System.Management.Automation.SwitchParameter</maml:name> </dev:type> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>View</maml:name> <maml:description /> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">Timeline</command:parameterValue> <command:parameterValue required="false" variableLength="false">Grouped</command:parameterValue> <command:parameterValue required="false" variableLength="false">GroupedDetail</command:parameterValue> </command:parameterValueGroup> <command:parameterValue required="true" variableLength="false">PSRPPacketView</command:parameterValue> <dev:type> <maml:name>RemoteWrench.PSRPPacketView</maml:name> </dev:type> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Width</maml:name> <maml:description /> <command:parameterValue required="true" variableLength="false">int</command:parameterValue> <dev:type> <maml:name>System.Int32</maml:name> </dev:type> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="Named" aliases="NoColour"> <maml:name>NoColor</maml:name> <maml:description> <maml:para>Disables ANSI color codes in the output. Use this when redirecting to a file or when color output is not desired.</maml:para> </maml:description> <dev:type> <maml:name>System.Management.Automation.SwitchParameter</maml:name> </dev:type> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="true (ByValue)" position="Named" aliases="none"> <maml:name>Packet</maml:name> <maml:description> <maml:para>The PSRP packet objects to format. Accepts pipeline input from `ConvertTo-PSRPPacket`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">RemoteWrench.OutOfProcPacket[]</command:parameterValue> <dev:type> <maml:name>RemoteWrench.OutOfProcPacket[]</maml:name> </dev:type> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="Named" aliases="none"> <maml:name>View</maml:name> <maml:description> <maml:para>The layout of the output, `Timeline` for the raw packet exchange, `Grouped` for the PSRP messages of each runspace pool and pipeline, or `GroupedDetail` for the grouped messages with their fragments and decoded fields. See the description for more details on each view. Defaults to `Timeline`.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">Timeline</command:parameterValue> <command:parameterValue required="false" variableLength="false">Grouped</command:parameterValue> <command:parameterValue required="false" variableLength="false">GroupedDetail</command:parameterValue> </command:parameterValueGroup> <command:parameterValue required="true" variableLength="true">RemoteWrench.PSRPPacketView</command:parameterValue> <dev:type> <maml:name>RemoteWrench.PSRPPacketView</maml:name> </dev:type> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="Named" aliases="none"> <maml:name>Width</maml:name> <maml:description> <maml:para>The width of the output in characters, between 40 and 1000. Defaults to the buffer width of the host, which is the console of the client in a remote session, or 120 when the host does not provide one. Summaries are truncated to the width, the fields of the `GroupedDetail` view are wrapped at the width or 120 characters, whichever is smaller.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">System.Int32</command:parameterValue> <dev:type> <maml:name>System.Int32</maml:name> </dev:type> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>RemoteWrench.OutOfProcPacket[]</maml:name> </dev:type> <maml:description> <maml:para>Parsed PSRP packet objects from `ConvertTo-PSRPPacket`.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>System.String</maml:name> </dev:type> <maml:description> <maml:para>A string for each formatted line.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para>The output uses box drawing and arrow characters that need the console to use UTF-8 to display correctly. Linux and macOS use UTF-8 by default but the Windows console uses a legacy code page unless changed, a warning is written on Windows when the console output encoding is not UTF-8. The warning is not written in a remote session, the output is sent back to the client and displayed with its console encoding. Set the console to UTF-8 with `[Console]::OutputEncoding = [Text.UTF8Encoding]::new()`, adding it to the PowerShell profile sets it for every session.</maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>--------- Example 1: Format packets from a log file ---------</maml:title> <maml:introduction> <maml:para>```powershell Get-Content psremoting.log | ConvertTo-PSRPPacket | Format-PSRPPacket ```</maml:para> <maml:para>€</maml:para> <maml:para>Reads, parses, and formats PSRP packets as a timeline with one line per message.</maml:para> </maml:introduction> <dev:code /> <dev:remarks /> </command:example> <command:example> <maml:title>--------- Example 2: Group the messages by runspace pool and pipeline ---------</maml:title> <maml:introduction> <maml:para>```powershell Get-Content psremoting.log | ConvertTo-PSRPPacket | Format-PSRPPacket -View Grouped ```</maml:para> <maml:para>€</maml:para> <maml:para>Shows what each pipeline did, with the runspace pool messages between them, without the acknowledgements and fragments of the transport.</maml:para> </maml:introduction> <dev:code /> <dev:remarks /> </command:example> <command:example> <maml:title>--------- Example 3: Follow a log as it is written ---------</maml:title> <maml:introduction> <maml:para>```powershell Get-Content psremoting.log -Wait | ConvertTo-PSRPPacket | Format-PSRPPacket -View GroupedDetail ```</maml:para> <maml:para>€</maml:para> <maml:para>Formats each message with its fragments and decoded fields as it is written to the log.</maml:para> </maml:introduction> <dev:code /> <dev:remarks /> </command:example> <command:example> <maml:title>--------- Example 4: Format packets without color to a file ---------</maml:title> <maml:introduction> <maml:para>```powershell Get-Content psremoting.log | ConvertTo-PSRPPacket | Format-PSRPPacket -NoColor -Width 200 | Set-Content psremoting.txt ```</maml:para> <maml:para>€</maml:para> <maml:para>Writes the timeline to a file without ANSI color codes, 200 characters wide regardless of the console size.</maml:para> </maml:introduction> <dev:code /> <dev:remarks /> </command:example> </command:examples> <command:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version</maml:linkText> <maml:uri>https://www.github.com/jborean93/PowerShell-RemoteWrench/blob/main/docs/en-US/RemoteWrench/Format-PSRPPacket.md</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>ConvertTo-PSRPPacket</maml:linkText> <maml:uri>./ConvertTo-PSRPPacket.md</maml:uri> </maml:navigationLink> </command:relatedLinks> </command:command> </helpItems> |