// WSUG Chapter Work [#ChapterWork] == Working With Captured Packets [#ChWorkViewPacketsSection] === Viewing Packets You Have Captured Once you have captured some packets or you have opened a previously saved capture file, you can view the packets that are displayed in the packet list pane by simply clicking on a packet in the packet list pane, which will bring up the selected packet in the tree view and byte view panes. You can then expand any part of the tree to view detailed information about each protocol in each packet. Clicking on an item in the tree will highlight the corresponding bytes in the byte view. An example with a TCP packet selected is shown in <>. It also has the Acknowledgment number in the TCP header selected, which shows up in the byte view as the selected bytes. [#ChWorkSelPack1] .Wireshark with a TCP packet selected for viewing image::images/ws-packet-selected.png[{screenshot-attrs}] You can also select and view packets the same way while Wireshark is capturing if you selected “Update list of packets in real time” in the “Capture Preferences” dialog box. In addition you can view individual packets in a separate window as shown in <>. You can do this by double-clicking on an item in the packet list or by selecting the packet in which you are interested in the packet list pane and selecting menu:View[Show Packet in New Window]. This allows you to easily compare two or more packets, even across multiple files. [#ChWorkPacketSepView] .Viewing a packet in a separate window image::images/ws-packet-sep-win.png[{screenshot-attrs}] Along with double-clicking the packet list and using the main menu there are a number of other ways to open a new packet window: - Hold down the shift key and double-click on a frame link in the packet details. - From <>. - From <>. [#ChWorkDisplayPopUpSection] === Pop-up Menus You can open a pop-up menu over the “Packet List”, its column heading, “Packet Details”, or “Packet Bytes” by clicking your right mouse button on the corresponding item. [#ChWorkColumnHeaderPopUpMenuSection] ==== Pop-up Menu Of The “Packet List” Column Header [#ChWorkColumnHeaderPopUpMenu] .Pop-up menu of the “Packet List” column header image::images/ws-column-header-popup-menu.png[{screenshot-attrs}] The following table gives an overview of which functions are available in this header, where to find the corresponding function in the main menu, and a description of each item. [#ColumnHeaderPopupMenuTable] .The menu items of the “Packet List” column header pop-up menu [options="header",cols="3,7"] |=== |Item |Description |menu:Align Left[] | Left-align values in this column. |menu:Align Center[] | Center-align values in this column. |menu:Align Right[] | Right-align values in this column. |menu:Column Preferences...[] | Open the “Preferences” dialog for this column. |menu:Edit Column[] | Open the column editor toolbar for this column. |menu:Resize To Contents[] | Resize the column to fit its values. |menu:Resolve Names[] | If this column contains addresses, resolve them. | _No., Time, Source, et al._ | Show or hide a column by selecting its item. |menu:Remove Column[] | Remove this column, similar to deleting it in the “Preferences” dialog. |=== [#ChWorkPacketListPanePopUpMenuSection] ==== Pop-up Menu Of The “Packet List” Pane [#ChWorkPacketListPanePopUpMenu] .Pop-up menu of the “Packet List” pane image::images/ws-packet-pane-popup-menu.png[{screenshot-attrs}] The following table gives an overview of which functions are available in this pane, where to find the corresponding function in the main menu, and a short description of each item. [#PacketListPopupMenuTable] .The menu items of the “Packet List” pop-up menu [options="header",cols="3,1,6"] |=== |Item |Corresponding main menu item |Description |menu:Mark Packet (toggle)[]|menu:Edit[]| Mark or unmark a packet. |menu:Ignore Packet (toggle)[]|menu:Edit[]| Ignore or inspect this packet while dissecting the capture file. |menu:Set Time Reference (toggle)[]|menu:Edit[]| Set or reset a time reference. |menu:Time Shift[] |menu:Edit[] | Opens the “Time Shift” dialog, which allows you to adjust the timestamps of some or all packets. |menu:Packet Comment...[] |menu:Edit[] | Opens the “Packet Comment” dialog, which lets you add a comment to a single packet. Note that the ability to save packet comments depends on your file format. E.g., pcapng supports comments, pcap does not. |menu:Edit Resolved Name[]|| Allows you to enter a name to resolve for the selected address. |menu:Apply as Filter[]|menu:Analyze[]| Immediately replace or append the current display filter based on the most recent packet list or packet details item selected. The first submenu item shows the filter and subsequent items show the different ways that the filter can be applied. |menu:Prepare as Filter[]|menu:Analyze[]| Change the current display filter based on the most recent packet list or packet details item selected, but don't apply it. The first submenu item shows the filter and subsequent items show the different ways that the filter can be changed. // XXX - add a new section describing this better. |menu:Conversation Filter[] || Apply a display filter with the address information from the selected packet. For example, the IP menu entry will set a filter to show the traffic between the two IP addresses of the current packet. |menu:Colorize Conversation[] || Create a new colorizing rule based on address information from the selected packet. |menu:SCTP[] || Allows you to analyze and prepare a filter for this SCTP association. |menu:Follow[TCP Stream] |menu:Analyze[] | Open a window that displays all the TCP segments captured that are on the same TCP connection as a selected packet. See <>. |menu:Follow[UDP Stream] |menu:Analyze[] | Same functionality as “Follow TCP Stream” but for UDP “streams”. |menu:Follow[DCCP Stream] |menu:Analyze[] | Same functionality as “Follow TCP Stream” but for DCCP streams. |menu:Follow[TLS Stream] |menu:Analyze[] | Same functionality as “Follow TCP Stream” but for TLS or SSL streams. See the wiki page on link:{wireshark-wiki-url}SSL[SSL] for instructions on providing TLS keys. |menu:Follow[HTTP Stream] |menu:Analyze[] | Same functionality as “Follow TCP Stream” but for HTTP streams. |menu:Copy[Summary as Text] || Copy the summary fields as displayed to the clipboard as tab-separated text. |menu:Copy[...as CSV] || Copy the summary fields as displayed to the clipboard as comma-separated text. |menu:Copy[...as YAML] || Copy the summary fields as displayed to the clipboard as YAML data. |menu:Copy[As Filter] || Prepare a display filter based on the currently selected item and copy that filter to the clipboard. |menu:Copy[Bytes as Hex + ASCII Dump] || Copy the packet bytes to the clipboard in full “hexdump” format. |menu:Copy[...as Hex Dump] || Copy the packet bytes to the clipboard in “hexdump” format without the ASCII portion. |menu:Copy[...as Printable Text] || Copy the packet bytes to the clipboard as ASCII text, excluding non-printable characters. |menu:Copy[...as a Hex Stream] || Copy the packet bytes to the clipboard as an unpunctuated list of hex digits. |menu:Copy[...as Raw Binary] || Copy the packet bytes to the clipboard as raw binary. The data is stored in the clipboard using the MIME type “application/octet-stream”. |menu:Protocol Preferences[] || Adjust the preferences for the selected protocol. |menu:Decode As...[] |menu:Analyze[] | Change or apply a new relation between two dissectors. |menu:Show Packet in New Window[] |menu:View[] | Shows the selected packet in a separate window. The separate window shows only the packet details and bytes. See <> for details. |=== [#ChWorkPacketDetailsPanePopUpMenuSection] ==== Pop-up Menu Of The “Packet Details” Pane [#ChWorkPacketDetailsPanePopUpMenu] .Pop-up menu of the “Packet Details” pane image::images/ws-details-pane-popup-menu.png[{screenshot-attrs}] The following table gives an overview of which functions are available in this pane, where to find the corresponding function in the main menu, and a short description of each item. [#PacketDetailsPopupMenuTable] .The menu items of the “Packet Details” pop-up menu [options="header",cols="3,1,6"] |=== |Item |Corresponding main menu item |Description |menu:Expand Subtrees[]|menu:View[]| Expand the currently selected subtree. |menu:Collapse Subtrees[]|menu:View[]| Collapse the currently selected subtree. |menu:Expand All[]|menu:View[]| Expand all subtrees in all packets in the capture. |menu:Collapse All[]|menu:View[]| Wireshark keeps a list of all the protocol subtrees that are expanded, and uses it to ensure that the correct subtrees are expanded when you display a packet. This menu item collapses the tree view of all packets in the capture list. |menu:Edit Resolved Name[]|menu:View[]| Allows you to enter a name to resolve for the selected address. |menu:Apply as Column[]|| Use the selected protocol item to create a new column in the packet list. |menu:Apply as Filter[]|menu:Analyze[]| Immediately replace or append the current display filter based on the most recent packet list or packet details item selected. The first submenu item shows the filter and subsequent items show the different ways that the filter can be applied. |menu:Prepare as Filter[]|menu:Analyze[]| Change the current display filter based on the most recent packet list or packet details item selected, but don't apply it. The first submenu item shows the filter and subsequent items show the different ways that the filter can be changed. |menu:Colorize with Filter[]|| This menu item uses a display filter with the information from the selected protocol item to build a new colorizing rule. |menu:Follow[TCP Stream] |menu:Analyze[] | Open a window that displays all the TCP segments captured that are on the same TCP connection as a selected packet. See <>. |menu:Follow[UDP Stream] |menu:Analyze[] | Same functionality as “Follow TCP Stream” but for UDP “streams”. |menu:Follow[TLS Stream] |menu:Analyze[] | Same functionality as “Follow TCP Stream” but for TLS or SSL streams. See the wiki page on link:{wireshark-wiki-url}SSL[SSL] for instructions on providing TLS keys. |menu:Follow[HTTP Stream] |menu:Analyze[] | Same functionality as “Follow TCP Stream” but for HTTP streams. |menu:Copy[All Visible Items] |menu:Edit[] | Copy the packet details as displayed. |menu:Copy[All Visible Selected Tree Items] |menu:Edit[] | Copy the selected packet detail and its children as displayed. |menu:Copy[Description] |menu:Edit[] | Copy the displayed text of the selected field to the system clipboard. |menu:Copy[Fieldname] |menu:Edit[] | Copy the name of the selected field to the system clipboard. |menu:Copy[Value] |menu:Edit[] | Copy the value of the selected field to the system clipboard. |menu:Copy[As Filter]| menu:Edit[] | Prepare a display filter based on the currently selected item and copy it to the clipboard. |menu:Copy[Bytes as Hex + ASCII Dump] || Copy the packet bytes to the clipboard in full “hexdump” format. |menu:Copy[...as Hex Dump] || Copy the packet bytes to the clipboard in “hexdump” format without the ASCII portion. |menu:Copy[...as Printable Text] || Copy the packet bytes to the clipboard as ASCII text, excluding non-printable characters. |menu:Copy[...as a Hex Stream] || Copy the packet bytes to the clipboard as an unpunctuated list of hex digits. |menu:Copy[...as Raw Binary] || Copy the packet bytes to the clipboard as raw binary. The data is stored in the clipboard using the MIME type “application/octet-stream”. |menu:Copy[...as Escaped String] || Copy the packet bytes to the clipboard as C-style escape sequences. |menu:Export Packet Bytes...[] |menu:File[] | This menu item is the same as the File menu item of the same name. It allows you to export raw packet bytes to a binary file. |menu:Wiki Protocol Page[]|| Open the wiki page for the selected protocol in your web browser. |menu:Filter Field Reference[]|| Open the filter field reference web page for the selected protocol in your web browser. |menu:Protocol Preferences[] || Adjust the preferences for the selected protocol. |menu:Decode As...[]|menu:Analyze[]| Change or apply a new relation between two dissectors. |menu:Go to Linked Packet[] |menu:Go[] | If the selected field has a corresponding packet such as the matching request for a DNS response, go to it. |menu:Show Linked Packet in New Window[] |menu:Go[] | If the selected field has a corresponding packet such as the matching request for a DNS response, show the selected packet in a separate window. See <> for details. |=== [#ChWorkPacketBytesPanePopUpMenuSection] ==== Pop-up Menu Of The “Packet Bytes” Pane [#ChWorkPacketBytesPanePopUpMenu] .Pop-up menu of the “Packet Bytes” pane image::images/ws-bytes-pane-popup-menu.png[{screenshot-attrs}] The following table gives an overview of which functions are available in this pane along with a short description of each item. [#PacketBytesPopupMenuTable] .The menu items of the “Packet Bytes” pop-up menu [options="header",cols="3,7"] |=== |Item |Description |menu:Copy Bytes as Hex + ASCII Dump[] | Copy the packet bytes to the clipboard in full “hexdump” format. |menu:...as Hex Dump[] | Copy the packet bytes to the clipboard in “hexdump” format without the ASCII portion. |menu:...as Printable Text[] | Copy the packet bytes to the clipboard as ASCII text, excluding non-printable characters. |menu:...as a Hex Stream[] | Copy the packet bytes to the clipboard as an unpunctuated list of hex digits. |menu:...as Raw Binary[] | Copy the packet bytes to the clipboard as raw binary. The data is stored in the clipboard using the MIME type “application/octet-stream”. |menu:...as Escaped String[] | Copy the packet bytes to the clipboard as C-style escape sequences. |menu:Show bytes as hexadecimal[] | Display the byte data as hexadecimal digits. |menu:Show bytes as bits[] | Display the byte data as binary digits. |menu:Show text based on packet[] | Show the “hexdump” data with text. |menu:...as ASCII[] | Use ASCII encoding when displaying “hexdump” text. |menu:...as EBCDIC[] | Use EBCDIC encoding when displaying “hexdump” text. |=== [#ChWorkPacketDiagramPanePopUpMenuSection] ==== Pop-up Menu Of The “Packet Diagram” Pane [#ChWorkPacketDiagramPanePopUpMenu] .Pop-up menu of the “Packet Diagram” pane image::images/ws-diagram-pane-popup-menu.png[{screenshot-attrs}] The following table gives an overview of which functions are available in this pane along with a short description of each item. [#PacketDiagramPopupMenuTable] .The menu items of the “Packet Diagram” pop-up menu [options="header",cols="3,7"] |=== |Item |Description |menu:Show Field Values[] | Display current value for each field on the packet diagram. |menu:Save Diagram As...[] | Save the packet diagram to an image file (PNG, BMP, JPEG). |menu:Copy as Raster Image[] | Copy the packet diagram to the clipboard in raster (ARGB32) format. // |menu:…as SVG[] | // (macOS) Copy the packet diagram to the clipboard in SVG format. |=== [#ChWorkDisplayFilterSection] === Filtering Packets While Viewing Wireshark has two filtering languages: _capture filters_ and _display filters_. _Capture filters_ are used for filtering when capturing packets and are discussed in <>. _Display filters_ are used for filtering which packets are displayed and are discussed below. For more information about _display filter_ syntax, see the link:{wireshark-man-page-url}wireshark-filter.html[wireshark-filter(4)] man page. Display filters allow you to concentrate on the packets you are interested in while hiding the currently uninteresting ones. They allow you to only display packets based on: * Protocol * The presence of a field * The values of fields * A comparison between fields * ... and a lot more! To only display packets containing a particular protocol, type the protocol name in the display filter toolbar of the Wireshark window and press enter to apply the filter. <> shows an example of what happens when you type _tcp_ in the display filter toolbar. [NOTE] ==== Protocol and field names are usually in lowercase. ==== [NOTE] ==== Don’t forget to press enter or click on the apply display filter button after entering the filter expression. ==== [#ChWorkTCPFilter] .Filtering on the TCP protocol image::images/ws-display-filter-tcp.png[{screenshot-attrs}] As you may have noticed, only packets containing the TCP protocol are now displayed, so packets 1-10 are hidden and packet number 11 is the first packet displayed. [NOTE] ==== When using a display filter, all packets remain in the capture file. The display filter only changes the display of the capture file but not its content! ==== To remove the filter, click on the btn:[Clear] button to the right of the display filter field. All packets will become visible again. Display filters can be very powerful and are discussed in further detail in <> It's also possible to create display filters with the _Display Filter Expression_ dialog box. More information about the _Display Filter Expression_ dialog box is available in <>. [#ChWorkBuildDisplayFilterSection] === Building Display Filter Expressions Wireshark provides a display filter language that enables you to precisely control which packets are displayed. They can be used to check for the presence of a protocol or field, the value of a field, or even compare two fields to each other. These comparisons can be combined with logical operators, like "and" and "or", and parentheses into complex expressions. The following sections will go into the display filter functionality in more detail. [TIP] ==== There are many display filter examples on the _Wireshark Wiki Display Filter page_ at: link:{wireshark-wiki-url}DisplayFilters[]. ==== ==== Display Filter Fields The simplest display filter is one that displays a single protocol. To only display packets containing a particular protocol, type the protocol into Wireshark's display filter toolbar. For example, to only display TCP packets, type _tcp_ into Wireshark's display filter toolbar. Similarly, to only display packets containing a particular field, type the field into Wireshark's display filter toolbar. For example, to only display HTTP requests, type _http.request_ into Wireshark's display filter toolbar. You can filter on any protocol that Wireshark supports. You can also filter on any field that a dissector adds to the tree view, if the dissector has added an abbreviation for that field. A full list of the available protocols and fields is available through the menu item menu:View[Internals,Supported Protocols]. // XXX - add some more info here and a link to the statusbar info. ==== Comparing Values You can build display filters that compare values using a number of different comparison operators. For example, to only display packets to or from the IP address 192.168.0.1, use `ip.addr==192.168.0.1`. A complete list of available comparison operators is shown in <>. [TIP] ==== English and C-like operators are interchangeable and can be mixed within a filter string. ==== [#DispCompOps] .Display Filter comparison operators [options="header",cols="1,1,1,3,3"] |=== | English | Alias | C-like | Description | Example | eq | any_eq | == | Equal (any if more than one) | `ip.src == 10.0.0.5` | ne | all_ne | != | Not equal (all if more than one) | `ip.src != 10.0.0.5` | | all_eq | === | Equal (all if more than one) | `ip.src === 10.0.0.5` | | any_ne | !== | Not equal (any if more than one) | `ip.src !== 10.0.0.5` | gt | | > | Greater than | `frame.len > 10` | lt | | < | Less than | `frame.len < 128` | ge | | >= | Greater than or equal to | `frame.len ge 0x100` | le | | \<= | Less than or equal to | `frame.len \<= 0x20` | contains | | | Protocol, field or slice contains a value | `sip.To contains "a1762"` | matches | | ~ | Protocol or text field matches a Perl-compatible regular expression| `http.host matches "acme\\.(org\|com\|net)"` |=== [NOTE] ==== The meaning of != (all not equal) was changed in Wireshark 3.6. Before it used to mean "any not equal". ==== All protocol fields have a type. <> provides a list of the types with examples of how to use them in display filters. [#ChWorkFieldTypes] ===== Display Filter Field Types Unsigned integer:: Can be 8, 16, 24, 32, or 64 bits. You can express integers in decimal, octal, hexadecimal or binary. The following display filters are equivalent: + `ip.len le 1500` + `ip.len le 02734` + `ip.len le 0x5dc` + `ip.len le 0b10111011100` Signed integer:: Can be 8, 16, 24, 32, or 64 bits. As with unsigned integers you can use decimal, octal, hexadecimal or binary. Boolean:: Can be 1 or "True", 0 or "False" (without quotes). + A Boolean field is present regardless if its value is true or false. For example, `tcp.flags.syn` is present in all TCP packets containing the flag, whether the SYN flag is 0 or 1. To only match TCP packets with the SYN flag set, you need to use `tcp.flags.syn == 1` or `tcp.flags.syn == True`. Ethernet address:: 6 bytes separated by a colon (:), dot (.), or dash (-) with one or two bytes between separators: + `eth.dst == ff:ff:ff:ff:ff:ff` + `eth.dst == ff-ff-ff-ff-ff-ff` + `eth.dst == ffff.ffff.ffff` IPv4 address:: `ip.addr == 192.168.0.1` + Classless InterDomain Routing (CIDR) notation can be used to test if an IPv4 address is in a certain subnet. For example, this display filter will find all packets in the 129.111 Class-B network: + `ip.addr == 129.111.0.0/16` IPv6 address:: `ipv6.addr == ::1` + As with IPv4 addresses, IPv6 addresses can match a subnet. Text string:: `http.request.uri == "https://www.wireshark.org/"` + Strings are a sequence of bytes. Functions like `lower()` use ASCII, otherwise no particular encoding is assumed. String literals are specified with double quotes. Characters can also be specified using a byte escape sequence using hex \x__hh__ or octal {backslash}__ddd__, where _h_ and _d_ are hex and octal numerical digits respectively: + `dns.qry.name contains "www.\x77\x69\x72\x65\x73\x68\x61\x72\x6b.org"` + Alternatively, a raw string syntax can be used. Such strings are prefixed with `r` or `R` and treat backslash as a literal character. + `http.user_agent matches r"\(X11;"` Date and time:: `frame.time == "Sep 26, 2004 23:18:04.954975"` + `ntp.xmt ge "2020-07-04 12:34:56"` + The value of an absolute time field is expressed as a string, using one of the two formats above. Fractional seconds can be omitted or specified up to nanosecond precision; extra trailing zeros are allowed but not other digits. The string cannot take a time zone suffix, and is always parsed as in the local time zone, even for fields that are displayed in UTC. + In the first format, the abbreviated month names must be in English regardless of locale. In the second format, any number of time fields may be omitted, in the order from least significant (seconds) to most, but at least the entire date must be specified: + `frame.time < "2022-01-01"` + In the second format, a `T` may appear between the date and time as in ISO 8601, but not when less significant times are dropped. [#ChWorkFilterExamples] ===== Some Examples ---- udp contains 81:60:03 ---- The display filter above matches packets that contains the 3-byte sequence 0x81, 0x60, 0x03 anywhere in the UDP header or payload. ---- sip.To contains "a1762" ---- The display filter above matches packets where the SIP To-header contains the string "a1762" anywhere in the header. ---- http.host matches "acme\\.(org|com|net)" ---- The display filter above matches HTTP packets where the HOST header contains acme.org, acme.com, or acme.net. Comparisons are case-insensitive. ---- tcp.flags & 0x02 ---- That display filter will match all packets that contain the “tcp.flags” field with the 0x02 bit, i.e., the SYN bit, set. ===== Possible Pitfalls Using Regular Expressions String literals containing regular expressions are parsed twice. Once by Wireshark's display filter engine and again by the PCRE2 library. It's important to keep this in mind when using the "matches" operator with regex escape sequences and special characters. For example, the filter expression `+frame matches "AB\x43"+` uses the string `+"ABC"+` as input pattern to PCRE. However, the expression `+frame matches "AB\\x43"+` uses the string `+"AB\x43"+` as the pattern. In this case both expressions give the same result because Wireshark and PCRE both support the same byte escape sequence (0x43 is the ASCII hex code for `C`). An example where this fails badly is `+foo matches "bar\x28"+`. Because 0x28 is the ASCII code for `(` the pattern input to PCRE is `+"bar("+`. This regular expression is syntactically invalid (missing closing parenthesis). To match a literal parenthesis in a display filter regular expression it must be escaped (twice) with backslashes. TIP: Using raw strings avoids most problem with the "matches" operator and double escape requirements. ==== Combining Expressions You can combine filter expressions in Wireshark using the logical operators shown in <> [#FiltLogOps] .Display Filter Logical Operations [options="header",cols="1,1,1,4"] |=== |English |C-like |Description | Example |and |&&| Logical AND | `ip.src==10.0.0.5 and tcp.flags.fin` |or |\|\| | Logical OR | `ip.src==10.0.0.5 or ip.src==192.1.1.1` |xor |^^ | Logical XOR | `tr.dst[0:3] == 0.6.29 xor tr.src[0:3] == 0.6.29` |not |! | Logical NOT | `not llc` |[...] | | Subsequence | See “Slice Operator” below. |in | | Set Membership| http.request.method in {"HEAD", "GET"}. See “Membership Operator” below. |=== ==== Slice Operator Wireshark allows you to select a subsequence of byte arrays (including protocols) or text strings in rather elaborate ways. After a label you can place a pair of brackets [] containing a comma separated list of range specifiers. ---- eth.src[0:3] == 00:00:83 ---- The example above uses the n:m format to specify a single range. In this case n is the beginning offset and m is the length of the range being specified. ---- eth.src[1-2] == 00:83 ---- The example above uses the n-m format to specify a single range. In this case n is the beginning offset and m is the ending offset. ---- eth.src[:4] == 00:00:83:00 ---- The example above uses the :m format, which takes everything from the beginning of a sequence to offset m. It is equivalent to 0:m ---- eth.src[4:] == 20:20 ---- The example above uses the n: format, which takes everything from offset n to the end of the sequence. ---- eth.src[2] == 83 ---- The example above uses the n format to specify a single range. In this case the element in the sequence at offset n is selected. This is equivalent to n:1. ---- eth.src[0:3,1-2,:4,4:,2] == 00:00:83:00:83:00:00:83:00:20:20:83 ---- Wireshark allows you to string together single ranges in a comma separated list to form compound ranges as shown above. You can use the slice operator on a protocol name, too, to slice the bytes associated with that protocol. The `+frame+` protocol can be useful, encompassing all the captured data (not including secondary data sources like decrypted data.) Offsets can be negative, indicating an offset from the end of a field. ---- frame[-4:4] == 0.1.2.3 frame[-4] == 0.1.2.3 ---- The two examples above both check the last four bytes of a frame. Slices of string fields yield strings, and are indexed on codepoint boundaries after conversation of the string to UTF-8, not bytes. ---- http.content_type[0:4] == "text" smpp.message_text[:10] == "Абвгдеёжзи" ---- The second example above will match regardless of whether the original string was in Windows-1251, UTF-8, or UTF-16, so long as the converted string starts with those ten characters. Byte slices can be directly compared to strings; this converts the string to the corresponding UTF-8 byte sequence. To compare string slices with byte sequences, use the @ operator, below. ==== The Layer Operator A field can be restricted to a certain layer in the protocol stack using the layer operator (#), followed by a decimal number: ip.addr#2 == 192.168.30.40 matches only the inner (second) layer in the packet. Layers use simple stacking semantics and protocol layers are counted sequentially starting from 1. For example, in a packet that contains two IPv4 headers, the outer (first) source address can be matched with "ip.src#1" and the inner (second) source address can be matched with "ip.src#2". For more complicated ranges the same syntax used with slices is valid: tcp.port#[2-4] means layers number 2, 3 or 4 inclusive. The hash symbol is required to distinguish a layer range from a slice. ==== The At Operator By prefixing the field name with an at sign (@) the comparison is done against the raw packet data for the field. A character string must be decoded from a source encoding during dissection. If there are decoding errors the resulting string will usually contain replacement characters: [subs="replacements"] ---- browser.comment == "string is ����" ---- The at operator allows testing the raw undecoded data: ---- @browser.comment == 73:74:72:69:6e:67:20:69:73:20:aa:aa:aa:aa ---- The syntactical rules for a bytes field type apply to the second example. [NOTE] ==== When a bytes field is compared with a literal string, it is compared with the UTF-8 representation of that string. The at operator compares a string field with the actual byte representation in the original encoding, which may not be UTF-8. As an example, SMPP has a bytes field, `+smpp.message+`, and a string field, `+smpp.message_text+`, that refer to the same data. If the first four characters of the message is the string "Text" in the UTF-16 encoding, the following filters all match. ---- smpp.message[:8] == 00:54:00:65:00:73:00:74 smpp.message[:8] == "\x00T\x00e\x00s\x00t" smpp.message_text[:4] == "Test" smpp.message_text[:4] == "\x54\x65\x73\x74" @smpp.message_text[:8] == 00:54:00:65:00:73:00:74 @smpp.message_text[:8] == "\x00T\x00e\x00s\x00t" ---- The following filters do *NOT* match. ---- @smpp.message_text[:4] == "\x00T\x00e\x00s\x00t" smpp.message[:4] == "Test" smpp.message[:8] == "Test" @smpp.message_text[:4] == "Test" @smpp.message_text[:8] == "Test" ---- The first filter above does not match because of operator precedence left-to-right; `+@smpp.message_text` is converted to bytes before the slice operator is applied, so the length of the necessary slice is 8. The other filters do not match because the literal string "Test" is always converted to its 4 octet UTF-8 representation when comparing against bytes, and it does not match the UTF-16 representation of the field bytes. ==== ==== Membership Operator Wireshark allows you to test a field for membership in a set of values or fields. After the field name, use the `in` operator followed by the set items surrounded by braces {}. For example, to display packets with a TCP source or destination port of 80, 443, or 8080, you can use `tcp.port in {80, 443, 8080}`. Set elements must be separated by commas. The set of values can also contain ranges: `tcp.port in {443,4430..4434}`. [NOTE] ==== The display filter ---- tcp.port in {80, 443, 8080} ---- is equivalent to ---- tcp.port == 80 || tcp.port == 443 || tcp.port == 8080 ---- However, the display filter ---- tcp.port in {443, 4430..4434} ---- is not equivalent to ---- tcp.port == 443 || (tcp.port >= 4430 && tcp.port <= 4434) ---- This is because comparison operators are satisfied when _any_ field matches the filter, so a packet with a source port of 56789 and destination port of port 80 would also match the second filter since `56789 >= 4430 && 80 \<= 4434` is true. In contrast, the membership operator tests a single field against the range condition. ==== Sets are not just limited to numbers, other types can be used as well: ---- http.request.method in {"HEAD", "GET"} ip.addr in {10.0.0.5 .. 10.0.0.9, 192.168.1.1..192.168.1.9} frame.time_delta in {10 .. 10.5} ---- ==== Arithmetic operators You can perform the arithmetic operations on numeric fields shown in <> [#ArithmeticOps] .Display Filter Arithmetic Operations [options="header",cols="1,1,4"] |=== |Name |Syntax | Description |Unary minus |-A | Negation of A |Addition |A + B | Add B to A |Subtraction |A - B | Subtract B from A |Multiplication |A * B | Multiply A times B |Division |A / B | Divide A by B |Modulo |A % B | Remainder of A divided by B |Bitwise AND |A & B | Bitwise AND of A and B |=== An unfortunate quirk in the filter syntax is that the subtraction operator must be preceded by a space character, so "A-B" must be written as "A -B" or "A - B". Arithmetic expressions can be grouped using curly braces. For example, frames where capture length resulted in truncated TCP options: ---- frame.cap_len < { 14 + ip.hdr_len + tcp.hdr_len } ---- ==== Functions The display filter language has a number of functions to convert fields, see <>. [#DispFunctions] .Display Filter Functions [options="header",cols="1,4"] |=== |Function|Description |upper |Converts a string field to uppercase. |lower |Converts a string field to lowercase. |len |Returns the byte length of a string or bytes field. |count |Returns the number of field occurrences in a frame. |string |Converts a non-string field to a string. |max |Return the maximum value for the arguments. |min |Return the minimum value for the arguments. |abs |Return the absolute value for the argument. |=== The `upper` and `lower` functions can used to force case-insensitive matches: `lower(http.server) contains "apache"`. To find HTTP requests with long request URIs: `len(http.request.uri) > 100`. Note that the `len` function yields the string length in bytes rather than (multi-byte) characters. Usually an IP frame has only two addresses (source and destination), but in case of ICMP errors or tunneling, a single packet might contain even more addresses. These packets can be found with `count(ip.addr) > 2`. The `string` function converts a field value to a string, suitable for use with operators like "matches" or "contains". Integer fields are converted to their decimal representation. It can be used with IP/Ethernet addresses (as well as others), but not with string or byte fields. For example, to match odd frame numbers: ---- string(frame.number) matches "[13579]$" ---- To match IP addresses ending in 255 in a block of subnets (172.16 to 172.31): ---- string(ip.dst) matches r"^172\.(1[6-9]|2[0-9]|3[0-1])\.[0-9]{1,3}\.255" ---- The functions max() and min() take any number of arguments of the same type and returns the largest/smallest respectively of the set. ---- max(tcp.srcport, tcp.dstport) <= 1024 ---- ==== Field References An expression of the form ${some.proto.field} is called a field reference. Its value is read from the corresponding field in the currently selected field in the GUI. This is a powerful way to build dynamic filters, such as frames since the last five minutes to the selected frame: ---- frame.time_relative >= ${frame.time_relative} - 300 ---- or all HTTP packets whose `+ip.dst` value equals the "A" record of the DNS response in the current frame: ---- http && ip.dst eq ${dns.a} ---- The notation of field references is similar to that of <> but they are syntactically distinct. Field references, like other complex filters, make excellent use cases for <>, <>, and <> [#ChWorkBuildDisplayFilterTransitional] ==== Sometimes Fields Change Names As protocols evolve they sometimes change names or are superseded by newer standards. For example, DHCP extends and has largely replaced BOOTP and TLS has replaced SSL. If a protocol dissector originally used the older names and fields for a protocol the Wireshark development team might update it to use the newer names and fields. In such cases they will add an alias from the old protocol name to the new one in order to make the transition easier. For example, the DHCP dissector was originally developed for the BOOTP protocol but as of Wireshark 3.0 all of the “bootp” display filter fields have been renamed to their “dhcp” equivalents. You can still use the old filter names for the time being, e.g., “bootp.type” is equivalent to “dhcp.type” but Wireshark will show the warning “"bootp" is deprecated” when you use it. Support for the deprecated fields may be removed in the future. ==== Some protocol names can be ambiguous In some particular cases relational expressions (equal, less than, etc.) can be ambiguous. The filter name of a protocol or protocol field can contain any letter and digit in any order, possibly separated by dots. That can be indistinguishable from a literal value (usually numerical values in hexadecimal). For example the semantic value of `fc` can be the protocol Fibre Channel or the number 0xFC in hexadecimal because the 0x prefix is optional for hexadecimal numbers. Any value that matches a registered protocol or protocol field filter name is interpreted semantically as such. If it doesn't match a protocol name the normal rules for parsing literal values apply. So in the case of 'fc' the lexical token is interpreted as "Fibre Channel" and not 0xFC. In the case of 'fd' it would be interpreted as 0xFD because it is a well-formed hexadecimal literal value (according to the rules of display filter language syntax) and there is no protocol registered with the filter name 'fd'. How ambiguous values are interpreted may change in the future. To avoid this problem and resolve the ambiguity there is additional syntax available. Values prefixed with a dot are always treated as a protocol name. The dot stands for the root of the protocol namespace and is optional). Values prefixed with a colon are always interpreted as a byte array. ---- frame[10:] contains .fc or frame[10] == :fc ---- If you are writing a script, or you think your expression may not be giving the expected results because of the syntactical ambiguity of some filter expression it is advisable to use the explicit syntax to indicate the correct meaning for that expression. [#ChWorkFilterAddExpressionSection] === The “Display Filter Expression” Dialog Box When you are accustomed to Wireshark’s filtering system and know what labels you wish to use in your filters it can be very quick to simply type a filter string. However, if you are new to Wireshark or are working with a slightly unfamiliar protocol it can be very confusing to try to figure out what to type. The “Display Filter Expression” dialog box helps with this. [TIP] ==== The “Display Filter Expression” dialog box is an excellent way to learn how to write Wireshark display filter strings. ==== [#ChWorkFilterAddExpression1] .The “Display Filter Expression” dialog box image::images/ws-filter-add-expression.png[{screenshot-attrs}] // Screenshot from Wireshark 3.1.1 When you first bring up the Display Filter Expression dialog box you are shown a tree of field names, organized by protocol, and a box for selecting a relation. Field Name:: Select a protocol field from the protocol field tree. Every protocol with filterable fields is listed at the top level. You can search for a particular protocol entry by entering the first few letters of the protocol name. By expanding a protocol name you can get a list of the field names available for filtering for that protocol. Relation:: Select a relation from the list of available relation. The _is present_ is a unary relation which is true if the selected field is present in a packet. All other listed relations are binary relations which require additional data (e.g. a _Value_ to match) to complete. + When you select a field from the field name list and select a binary relation (such as the equality relation ==) you will be given the opportunity to enter a value, and possibly some range information. Value:: You may enter an appropriate value in the _Value_ text box. The _Value_ will also indicate the type of value for the _Field Name_ you have selected (like character string). Predefined Values:: Some of the protocol fields have predefined values available, much like enumerations in C. If the selected protocol field has such values defined, you can choose one of them here. Search:: Lets you search for a full or partial field name or description. Regular expressions are supported. For example, searching for “tcp.*flag” shows the TCP flags fields supported by a wide variety of dissectors, while “^tcp.flag” shows only the TCP flags fields supported by the TCP dissector. Range:: A range of integers or a group of ranges, such as `1-12` or `39-42,98-2000`. btn:[Help]:: Opens this section of the User’s Guide. btn:[OK]:: When you have built a satisfactory expression click btn:[OK] and a filter string will be built for you. btn:[Cancel]:: You can leave the “Add Expression...” dialog box without any effect by clicking the btn:[Cancel] button. [#ChWorkDefineFilterSection] === Defining And Saving Filters You create pre-defined filters that appear in the capture and display filter bookmark menus (image:images/toolbar/filter-toolbar-bookmark.png[height=16,width=12]). This can save time in remembering and retyping some of the more complex filters you use. To create or edit capture filters, select menu:Manage Capture Filters[] from the capture filter bookmark menu or menu:Capture[Capture Filters...] from the main menu. Display filters can be created or edited by selecting menu:Manage Display Filters[] from the display filter bookmark menu or menu:Analyze[Display Filters...] from the main menu. Wireshark will open the corresponding dialog as shown in <>. The two dialogs look and work similar to one another. Both are described here, and the differences are noted as needed. [#FiltersDialog] .The “Capture Filters” and “Display Filters” dialog boxes image::images/ws-filters.png[{screenshot-attrs}] btn:[{plus}]:: Adds a new filter to the list. You can edit the filter name or expression by double-clicking on it. + The filter name is used in this dialog to identify the filter for your convenience and is not used elsewhere. You can create multiple filters with the same name, but this is not very useful. + When typing in a filter string, the background color will change depending on the validity of the filter similar to the main capture and display filter toolbars. btn:[-]:: Delete the selected filter. This will be greyed out if no filter is selected. // XXX Asciidoctor doesn't seem to allow images in DL terms, otherwise we could use // list-copy.template.png here. btn:[Copy]:: Copy the selected filter. This will be greyed out if no filter is selected. btn:[OK]:: Saves the filter settings and closes the dialog. btn:[Cancel]:: Closes the dialog without saving any changes. [#ChWorkDefineFilterMacrosSection] === Defining And Saving Filter Macros You can define a filter macro with Wireshark and label it for later use. This can save time in remembering and retyping some of the more complex filters you use. To define and save your own filter macros, follow the steps below: . In the main menu select menu:Analyze[Display Filter Macros...]. Wireshark will open a corresponding dialog <>. + [#FilterMacrosDialog] + .Display Filter Macros window image::images/ws-filter-macros.png[{screenshot-attrs}] . To add a new filter macro, click the btn:[{plus}] button in the bottom-left corner. A new row will appear in the Display Filter Macros table above. . Enter the name of your macro in the `Name` column. Enter your filter macro in the `Text` column. . To save your modifications, click the btn:[OK] button in the bottom-right corner of the <>. To learn more about display filter macro syntax, see <>. [#ChWorkFindPacketSection] === Finding Packets You can easily find packets once you have captured some packets or have read in a previously saved capture file. Simply select menu:Edit[Find Packet...] in the main menu. Wireshark will open a toolbar between the main toolbar and the packet list shown in <>. ==== The “Find Packet” Toolbar [#ChWorkFindPacketToolbar] .The “Find Packet” toolbar image::images/ws-find-packet.png[{screenshot-attrs}] You can search using the following criteria: Display filter:: Enter a display filter string into the text entry field and click the btn:[Find] button. + For example, to find the three-way handshake for a connection from host 192.168.0.1, use the following filter string: + ---- ip.src==192.168.0.1 and tcp.flags.syn==1 ---- + The value to be found will be syntax checked while you type it in. If the syntax check of your value succeeds, the background of the entry field will turn green, if it fails, it will turn red. For more details see <> Hexadecimal Value:: Search for a specific byte sequence in the packet data. + For example, use “ef:bb:bf” to find the next packet that contains the link:{wikipedia-main-url}Byte_order_mark[UTF-8 byte order mark]. String:: Find a string in the packet data, with various options. Regular Expression:: Search the packet data using link:{pcre2pattern-url}[Perl-compatible regular expressions]. PCRE patterns are beyond the scope of this document, but typing “pcre test” into your favorite search engine should return a number of sites that will help you test and explore your expressions. [#ChWorkGoToPacketSection] === Go To A Specific Packet You can easily jump to specific packets with one of the menu items in the menu:Go[] menu. ==== The “Go Back” Command Go back in the packet history, works much like the page history in most web browsers. ==== The “Go Forward” Command Go forward in the packet history, works much like the page history in most web browsers. ==== The “Go to Packet” Toolbar [#ChWorkGoToPacketToolbar] .The “Go To Packet” toolbar image::images/ws-goto-packet.png[{screenshot-attrs}] This toolbar can be opened by selecting menu:Go[Go to packet...] from the main menu. It appears between the main toolbar and the packet list, similar to the <>. When you enter a packet number and press btn:[Go to packet] Wireshark will jump to that packet. ==== The “Go to Corresponding Packet” Command If a protocol field is selected which points to another packet in the capture file, this command will jump to that packet. As these protocol fields now work like links (just as in your Web browser), it’s easier to simply double-click on the field to jump to the corresponding field. ==== The “Go to First Packet” Command This command will jump to the first packet displayed. ==== The “Go to Last Packet” Command This command will jump to the last packet displayed. [#ChWorkMarkPacketSection] === Marking Packets You can mark packets in the “Packet List” pane. A marked packet will be shown with black background, regardless of the coloring rules set. Marking a packet can be useful to find it later while analyzing in a large capture file. Marked packet information is not stored in the capture file or anywhere else. It will be lost when the capture file is closed. You can use packet marking to control the output of packets when saving, exporting, or printing. To do so, an option in the packet range is available, see <>. There are several ways to mark and unmark packets. From the menu:Edit[] menu you can select from the following: * menu:Mark/Unmark Packet[] toggles the marked state of a single packet. This option is also available in the packet list context menu. * menu:Mark All Displayed[] set the mark state of all displayed packets. * menu:Unmark All Displayed[] reset the mark state of all packets. You can also mark and unmark a packet by clicking on it in the packet list with the middle mouse button. [#ChWorkIgnorePacketSection] === Ignoring Packets You can ignore packets in the “Packet List” pane. Wireshark will then pretend that they not exist in the capture file. An ignored packet will be shown with white background and grey foreground, regardless of the coloring rules set. Ignored packet information is not stored in the capture file or anywhere else. It will be lost when the capture file is closed. There are several ways to ignore and unignore packets. From the menu:Edit[] menu you can select from the following: * menu:Ignore/Unignore Packet[] toggles the ignored state of a single packet. This option is also available in the packet list context menu. * menu:Ignore All Displayed[] set the ignored state of all displayed packets. * menu:Unignore All Displayed[] reset the ignored state of all packets. [#ChWorkTimeFormatsSection] === Time Display Formats And Time References While packets are captured, each packet is timestamped. These timestamps will be saved to the capture file, so they will be available for later analysis. A detailed description of timestamps, timezones and alike can be found at: <>. The timestamp presentation format and the precision in the packet list can be chosen using the View menu, see <>. The available presentation formats are: * menu:Date and Time of Day: 1970-01-01 01:02:03.123456[] The absolute date and time of the day when the packet was captured. * menu:Time of Day: 01:02:03.123456[] The absolute time of the day when the packet was captured. * menu:Seconds Since First Captured Packet: 123.123456[] The time relative to the start of the capture file or the first “Time Reference” before this packet (see <>). * menu:Seconds Since Previous Captured Packet: 1.123456[] The time relative to the previous captured packet. * menu:Seconds Since Previous Displayed Packet: 1.123456[] The time relative to the previous displayed packet. * menu:Seconds Since Epoch (1970-01-01): 1234567890.123456[] The time relative to epoch (midnight UTC of January 1, 1970). The available precisions (aka. the number of displayed decimal places) are: * menu:Automatic (from capture file)[] The timestamp precision of the loaded capture file format will be used (the default). * menu:Seconds[], menu:Tenths of a second[], menu:Hundredths of a second[], menu:Milliseconds[], menu:Microseconds[] or menu:Nanoseconds[] The timestamp precision will be forced to the given setting. If the actually available precision is smaller, zeros will be appended. If the precision is larger, the remaining decimal places will be cut off. Precision example: If you have a timestamp and it’s displayed using, “Seconds Since Previous Packet” the value might be 1.123456. This will be displayed using the “Automatic” setting for libpcap files (which is microseconds). If you use Seconds it would show simply 1 and if you use Nanoseconds it shows 1.123456000. [#ChWorkTimeReferencePacketSection] ==== Packet Time Referencing The user can set time references to packets. A time reference is the starting point for all subsequent packet time calculations. It will be useful, if you want to see the time values relative to a special packet, e.g., the start of a new request. It’s possible to set multiple time references in the capture file. The time references will not be saved permanently and will be lost when you close the capture file. Time referencing will only be useful if the time display format is set to “Seconds Since First Captured Packet”. If one of the other time display formats are used, time referencing will have no effect (and will make no sense either). To work with time references, choose one of the menu:Time Reference[] items in the menu:[Edit] menu or from the pop-up menu of the “Packet List” pane. See <>. * menu:Set Time Reference (toggle)[] Toggles the time reference state of the currently selected packet to on or off. * menu:Find Next[] Find the next time referenced packet in the “Packet List” pane. * menu:Find Previous[] Find the previous time referenced packet in the “Packet List” pane. [#ChWorkTimeReference] .Wireshark showing a time referenced packet image::images/ws-time-reference.png[{screenshot-attrs}] A time referenced packet will be marked with the string $$*REF*$$ in the Time column (see packet number 10). All subsequent packets will show the time since the last time reference. [#ChWorkShiftTimePacketSection] === Time Shifting Packets Sometimes you will want to adjust the timestamps in a capture file. This may be because a machine performing the capture had an inaccurate clock, or because the capture was originally saved with timestamps in <> (perhaps even to a capture file format that only writes times in local time, or only writes the time of day but not the date). One common use is to synchronize timestamps between captures made on different machines with relative clock skew or clock drift before <> them. Selecting menu:Edit[Time Shift...] from the main menu opens the "Time Shift" dialog. .The “Time Shift” dialog image::images/ws-time-shift.png[{medium-screenshot-attrs}] Shift all packets by...:: Apply a fixed offset, entered as a relative time in hours, minutes, and seconds, to the timestamps for all packets. This is useful for correcting small known errors or timezones. Set the time for packet...:: Apply offsets based on one or, if the box is checked, two given packets to the timestamps for all packets. Enter the packet number and absolute date and time for the packet(s). When one packet is used, a fixed offset is applied that can be used to correct for clock skew. When two packets are used, the correction for all other packets is computed linearly, which can be used to correct for clock drift. This is useful when the precise date and time for particular packets are known, e.g. packets containing the NTP or PTP protocols. Undo all shifts:: This removes all unsaved time shifts from packets. [NOTE] .Time shifts are applied to all packets ==== Time shifts are applied to all packets in the capture, including ignored packets and packets that are not displayed due to the current filter. Wireshark does not have a method to adjust the timestamps of individual or selected packets. ==== The offset currently applied to time shifted packets is in the `frame.offset_shift` field, which can be viewed in the packet details. .A Time Shifted Packet image::images/ws-time-shift-details.png[{medium-screenshot-attrs}] After time shifts are applied, the file will have unsaved changes, which are indicated with an {asterisk} beside its name in the title bar. Beginning with Wireshark 4.2.0, <> the file will write the corrected timestamps to the capture file. If you attempt to close the capture file without saving it, a dialog will prompt you to save in order to prevent losing your changes (unless that warning has been disabled in the <>.) // End of WSUG Chapter Work