What is WireEdit?
WireEdit is a free desktop WYSIWYG editor for network packets. It allows editing any stack layer as "rich text" without having any knowledge of packets syntax and encoding rules. The input and output file format is Pcap.
Open a Pcap file → Edit as "rich text" → Save as a Pcap file
Look Ma, it's just like a packet analyzer!
Start WireEdit and open a Pcap file with File>>Open command. You can use one of our examples Pcap files, or your own file. As in a packet analyzer, packets are fully decoded with each element of the decode tree linked back to the encoded data.
What is PDU?
In a networking protocol a message for passing of information within a specific stack layer is called Packet Data Unit or PDU.
A network packet data structure is similar to a Russian nesting doll ("Matreshka") - a PDU of a stack layer 2 placed as data field (encapsulated) inside a PDU of a stack layer 1, a PDU of a stack layer 3 is encapsulated in a PDU of a stack layer 2, and so forth. It's not uncommon to have multiple PDUs of layer N encapsulated into a PDU of stack layer N-1.
Lets Begin Editing
Double-click any element of the packet decode tree, and Edit PDU dialog with the PDU of the element opens up. The dialog has two complementary editing panes: Encoded Pane (top) and Decoded Pane (bottom).
All the data elements specified for the PDU we have opened are present in the Decoded Pane data tree, some initially hidden from view. The hidden elements are made visible by clicking [+] icons in the left edge of Name column.
An element of the PDU data tree is either already a part of, or may be included into the current packet.
The changes made in Decoded Pane are automatically reflected in Encoded Pane, but not the other way around. To sync Decoded Pane with updated Encoded Pane click Decode button.
Decoded Pane → (Autosync) → Encoded Pane
Encoded Pane → (Click Decode button) → Encoded Pane
Adding/Deleting PDU Elements
All elements which MUST, SHOULD or MAY (See RFC2119) be present in the PDU are included into the Decoded Pane data tree. Just select the ones you need.
PDU elements belong to three major categories: Mandatory, Optional and Conditional. Mandatory elements are always present in a syntactically correct packet. Optional elements may or may not. An element of a Conditional type has to be present when the condition attached to it — usually a specific value of another field — is met. Conditional elements are managed automatically by WireEdit. The grayed out lines in Decoded Pane are the Optional and Conditional elements not currently included in the packet.
Each Optional element has a controlling checkbox. Add the element to a packet by selecting, delete by clearing it.
Each Conditional element has a presence indicator in a shape of a question mark with the condition of presence spelled out on the right of it. The elements with the green indicator (?) are currently included in the packet, with the red one (?) are not. A user can not change the indicator directly.
In the following screenshot we have added an optional Port Description element.
Change Field Value
One can assign a new value to a field by making changes in Value column.
Edit PDU dialog
Edit PDU is the main packet editing dialog. It contains two editing panes, and a number of control elements. We enumerate and briefly describe them all in the table below.
To exit Edit PDU dialog without changing a single bit in the packet binary, use Cancel button. If you click OK, auto-calculated fields of the packet may change even if no user initiated changes have been made.
|Item||What it is?|
|1||Encoded Pane containing binary PDU data as it would appear on the wire. You can edit Encoded Pane data directly and mirror the changes to Decoded Pane below it.|
|2||ASCII representation of Encoded Pane bin data on the left.|
|3||Encoded Pane buttons: Insert, Decode, Restore.|
|4||Switch to editing in Encoded Pane.|
|5||Switch to editing in Decoded Pane.|
|6||Show the encoded data as text. Useful for text based protocols like HTTP.|
|7||Decoded Pane showing a complete data tree of a PDU with all the mandatory, optional and conditional elements defined by the relevant specs.|
|8||Switch between Dec and Hex offset format in the leftmost column (column Offset).|
WireEdit guarantees packets remain syntactically correct while been edited via Decoded Pane. The pane provides protection from user errors and should be used by default. The protection can be disabled for individual fields if necessary. See Field Overwrite below.
Direct editing of reassembled by WireEdit TCP packets (not seen on the wire) is not currently supported. You can edit the real (seen on the wire) packets included in the reassembled packet.
Decoded Pane is the larger one of Edit PDU dialog panes. It contains a graphical tree representing the data structure of the PDU. Column Name has the names of the fields as rows. Field values could be changed by editing cells in Value column. Some field values have to be selected from a drop-down list.
Changes in Value column are checked against the specs and reflected in Encoded Pane on-the-fly. The illegal entries are immediately marked in red.
WireEdit guarantees packets remain syntactically correct after been edited via Decoded Pane. All the adjustments to the packet binary required to accommodate the changes made (checksum fields, length fields, offset fields, encoding, etc.) are performed on-the-fly. In fact, any field value defined as a function of other field values is auto-calculated on-the-fly.
The auto-calculated values are displayed in red and marked with "(auto-calculated)" text comment. These values can't be changed directly in the default editing mode.
Click Ok at the bottom right of the dialog and the changes will be incorporated into the packet. Run File>>Save command to have the changes saved to the file.
Editing in this pane is error-prone and makes it really easy to break the integrity of the packet. To verify your changes click Decode button on the right side of the pane. If possible, use Decoded Pane instead.
Encoded Pane is the pane at the top of Edit PDU dialog. It allows modifying encoded packet data directly. To enable editing in this pane select Edit Encoded radio button.
The pane contains binary PDU data as it would appear on the wire. In other words, if we send the packet to a network and capture it with a protocol analyzer, these are the exact bytes captured.
For binary layers – TCP in the screenshot above – Encoded Pane has two sub-panes, one with data in Hex on the left, the other with the same data in ASCII on the right. Both sub-panes are editable. One can switch between them with a mouse click. At the screenshot above the TCP PDU has some text in its right sub-pane because of HTTP data on top of TCP.
For text protocol layers — HTTP in the screenshot below — the data is shown by default as text.
Field Overwrite (fuzzing)
If you like living dangerously this feature is for you. It allows to build broken packets of your choice via Decoded Pane. Proceed on your own peril!
In Decoded Pane an individual packet field may have input syntax control disabled by the user. For that to happen one should select Overwrite with raw data command from the Value column context menu.
In Overwrite with raw data mode one could overwrite a field with any data. Please note there is no guarantees WireEdit would be able to successfully encode the packet after the overwrite.
WireEdit has a powerful and flexible packet filtering engine. For example, it allows to temporary hide all "do not edit" packets, run a Edit>>Replace | Replace All bulk packet scrubbing operation on the remaining set, then clear the filter to make the hidden packets visible again, unchanged.
Filtering may produce all kinds of unexpected and confusing effects. For example, trying to filter out from a log everything but HTTP packets, if done naively, may drop TCP segments with partial HTTP data, therefore break the HTTP reassembly and produce the log still containing TCP packets without HTTP PDU!
Open the filters dialog with Edit>>Filter command.
The dialog allows filtering by PDU type and by message types within a PDU type. All the PDUs (stack layers) are tied by radio button controlled AND/OR logic.
For example, suppose you have a capture of protocol X running over both TCP and UDP transport. If you select only X and TCP checkboxes, and AND logic radio button, you'd have only X over TCP packets left in the file after filtering. If you select OR logic, you'll have all TCP packets in the file, plus X over UDP packets.
Find all packets with a specific PDU (protocol layer) or group of PDUs present.
The filter group in the upper right allows to filter by IP Add/Port and direction. You can use it to find packets belonging to a TCP connection, for example.
Filtering could be done with a direct char string match or RegRx match of decoded packet data in Value column.
Char string match is the default. If you want to use regex syntax, enable it via the checkbox at the bottom right of Packet Filter dialog. C++11 regex syntax is fully supported.
Two independent filters linked by AND/OR logic allows filtering packet data in Decoded Pane as text. Both filters are disabled by default (Off). To enable the filter, select Include (show only packets matching the search criteria), or Exclude (exclude such packets).
Filtering could be done with a char string or regex match. Char string match mode is the default. It is simpler to use and often sufficient. Switching between the two modes is done via the checkbox in the lower right of Packet filter dialog.
Distillers are really helpful for quickly building context filter strings. They provide a compete list of char strings present in the decoded log. Try them out.
Edit>>Find command allows text search of decoded packet data in Value column.
The command supports a direct char string match and a regex match. Direct char string match is the default. If you want to use the regex syntax, enable it via the associated checkbox in Find dialog. C++11 regex syntax is fully supported.
Edit>>Replace command allows Find/Replace change of network packets data at any stack layer. Just enter the data you want to replace, and the data to replace it with. This capability makes bulk scrubbing (sanitizing, anonymizing) packets easy.
Replacing Decoded Data
A packet data fragment is decoded by WireEdit when it is recognized as a separate field (has a named row dedicated to it) and represented in Value column by anything but a sequence of bytes in Hex format. For decoded fields one can replace any sequence of text characters in Value column with any other sequence of text characters of a possibly different (!) length.
Replacing Binary Data
Some elements of packets are presented by WireEdit only as a sequence of bytes. This happens when the protocol layer is not yet supported, the support is incomplete/buggy, the data is encoded in a proprietary format, etc. Still the field value can be edited by replacing all or part of the binary data with other binary data. The modified data may have a different (!) number of bytes.
An undecoded element value is shown in Value column as an octet data string. An octet data string, or "an octet string" is a sequence of bytes in Hex format with a space character separating the consecutive bytes.
Below the octet string aa bb cc is replaced by a longer octet string (ff ff ff ff) at an OpenFlow 1.2 layer.
The regex syntax referred above is supported. One can use it to define the octet string to be replaced.
When replacing an octet string select from the list at the bottom of the dialog the stack layer where the change should take place. If you fail to do so, some fields in the modified packet may not be recalculated correctly. As a result you may notice an increase of Errors and warnings counter at the bottom right of the main dialog (see the screenshot below). Use Edit>>Fix Errors command to fix the errors.
Many pcap files one could find 'in the wild' have packets with cheksum errors. This is due to the fact that for speed reason some checksum calculations are performed at the Ethernet chip, and locally originated packets are captured into a pcap file before they get to the chip. Edit>>Fix Errors command force the checksum recalculations.
One could select a subset of packets and delete them with Edit>>Delete Selected Packets command. To keep the selected packets and delete the rest use Edit>>Delete All But Selected Packets command.
It is possible to modify an individual packet timestamp or add a fixed time shift to a range of selected packets.
Sorting by Timestamps
Open the dialog with Tools>>Options command.
Options | Protocols
Many protocols don't have unique port numbers assigned to them by standards bodies. They may run on a range of ports or any port. Sometimes a protocol with known standard ports runs on a non-standard ones. To modify Protocols ↔ Ports assignment table run Tools>>Options command and select Protocols tab.
Suppose you want to decode HTTP on a port other than 80 — just add the port number to the HTTP row, Port(s) column. To cover a range of ports from X to Y, enter X-Y (for example: 99-9800).
Options | Timestamps
On Timestamps tabbed page one can configure a format of the packets timestamps.
Options | Decode Details
On Decode Details tabbed page one can configure the packets decode format.
Options | Fonts & Colors
On Fonts and Colors tabbed page one can configure fonts and colors used by WireEdit to display elements of the decode tree.
Options | Misc
This tabbed page has a check box for controlling WireEdit auto-updates.
Currently TCP reassembly algorithm ignores out-of-order segments. WireEdit generates reassembled packets incorrectly when such segments are present in a TCP flow.