CloudShark Support

CloudShark User Guide

Getting Started

This guide contains general information on all the CloudShark apppliance’s features and capabilities. This guide is intended for both admin and non-admin users. Please see the CloudShark Admin Guide for a discussion of all Administration settings and configuration options available to admin users.

Logging In

Guest access is disabled by default on the CloudShark appliance. When guest access is disabled, all users must log in to upload or view capture files on the CloudShark appliance. CloudShark users can exist locally or externally, as discussed in the Users & Groups section of the Admin Guide. Users without an account, or with a lost password, should contact their CloudShark admin for assistance.

Note that users can always log in or out at any time using the Log In or Log Out link in the upper right corner.

User Preferences

CloudShark users (non-admin) can modify their specific preferences after logging in by clicking on the My Account link under the Preferences menu in the top right corner. The My Account pop-up allows users to change their password, assign a default group to their uploaded capture files, and set read-only or read-write permission for all uploaded captures.

If the CloudShark Administrator has enabled quotas the current usage can be viewed by clicking on Usage Quotas under the Preferences menu.

The Capture File Index

The capture file index is the homepage for any logged-in CloudShark user. It shows all the capture files that are available to the user.

Each column header in the capture file index can be clicked to sort the list on that column. A second click will reverse the order of the column. If the number of capture files in the index spans multiple pages, additional navigational links will be displayed in the top right corner of the table, along with the total number of capture files in the index.

To view other pages, use the First, Previous, Next, and Last links in the index header, or click on a specific page number. The number of results displayed per page is 30 by default.

CloudShark can sort and filter on most attributes of a capture file. The Table Options button in the toolbar allows users to define a custom column.

The Refresh button will reload the page, and has the same effect as using the refresh button on the web browser’s menu.

Capture files can also be tagged, deleted, or shared directly from the capture file index page using the Add Tags, Delete, and Sharing buttons, if the current user has the appropriate privileges for the selected file(s). See the section on sharing for more information on the different sharing options that are available.

Clicking on any row in the capture file index will open that capture file in the decoder window for viewing, analysis, and annotation. Holding the CTRL key (COMMAND on Mac) while clicking a row will open the capture file in a new tab within the browser.

Searching the Capture File Index

The CloudShark appliance includes an advanced search feature for drilling down and quickly finding specific capture files on the system.

CloudShark’s search feature allows multiple search filters to be applied to the capture file index. An individual search filter can be removed from the search list by clicking on the “X” in the top right corner of the filter box.

Likewise, favorite search filters can be pinned to the side of the captures index by clicking on the small pin icon. Pinned search filters are stored per user and will persist even when the user logs in from a different location.

The current search can be cleared entirely at any time by clicking the reset link. Pinned search filters will remain pinned if the reset link is clicked.

Available Search Fields

The following search filters are available:

  • File Name: Search for files with a specific text string in the filename. This is a useful way to find files uploaded by URL, since the URL is saved as the filename.

  • User: Search for files owned by a specific user.

  • Group: Search for files associated with a specific group.

  • Sharing: Search for files based on various sharing attributes.

  • Comments & Annotations: Search for files that have comments or annotations, or search for files with comments that contain specific text strings.

  • Tagged: Search for files with specific tags. Selecting Match Any will match captures with any of the specified tags. Selecting Match All will only match captures that have all of the specified tags.

  • Uploaded Date: Search for files uploaded between specific dates. For example, search for files uploaded within the past 7 days.

  • Upload Time: Search for files uploaded between specific times. For example, search for files uploaded between 12:00 AM and 1:00 AM.

  • Capture Date: Search for files containing packets that were captured on or between specific dates. For example, search for files containing packets captured within the past 7 days.

  • Capture Time: Search for files containing packets that were captured on or between specific times. For example, search for files containing packets captured between 12:00 AM and 1:00 AM.

  • Encapsulation: Search for files with packets containing specific encapsulations.

  • Type: Search for files of a certain type. This is most commonly libpcap.

  • File Size: Search for files of a certain size. This search filter allows exact size matching or comparative matching based on the size of the capture file, which is the data encapsulated in the packets plus the packet structures.

  • Data Size: Similar to the File Size search filter, this allows for searching based on the size of just the data encapsulated.

  • Duration: Search for files with based on the duration of the captured session, in seconds. This search filter allows exact or comparative matching of the capture session duration.

  • Packets: Search for files based on the number of packets. This search filter allows exact or comparative matching of the number of packets.

  • Byte Rate: Search for files based on the average number of bytes transferred per second.

  • Bit Rate: Similar to the Byte Rate filter, but measured in bits.

  • Average Packet Size: Search for files based on the average packet size, in bytes.

  • Average Packet Rate: Search for files based on the average number of packets captured per second.

  • SHA-1 Hash: Search for files based on the SHA-1 Hash of the capture file.

Clicking the Search button after defining a search list will display all capture files that match the search criteria. Clicking reset will clear all non-pinned search criteria and return to the default index.

Capture File Information

There is an info icon next to each file in the capture index. Clicking on this icon will open the Info pop-up box. This pop-up is also available when looking at a decode session by clicking on the Info button in the top right corner. The info pop-up box has four major sections:

  • File Info: The File Info section displays general information about the capture file. From here a user can also download the original capture file, delete the capture file, and view the capture file in the Decoder Window.

  • Tags: The Tags section displays any tags currently applied to the capture file. Tags can also be added or removed here by the owner of the file, admin users, or other group members (if read/write permission is enabled).

  • Comments: The Comments section displays any comments currently applied to the capture file. Comments can also be added or removed here by the owner of the file, admin users, or other group members (if read/write permission is enabled).

  • Sharing: The Sharing section displays various group access and guest access attributes of the file. These settings can only be modified by the owner of the file and admin users. See the Sharing Capture Files section for more information on these settings.

Meta data such as Tags, Comments, and Annotations are discussed in detail in the Capture File Meta Data section.

Uploading Capture Files

Regardless of whether or not guest access is enabled, there are five primary methods for importing capture files to the CloudShark appliance. Please see the section importing capture files for more information.

Viewing Capture Files - The Decoder Window

Clicking on a row in the capture file index table will open the selected capture file in the decoder window.

The decoder window is a deconstructed view of the capture file. By default, the first packet in the capture file is highlighted in the top frame. To load other packets within the capture file, click their corresponding row. The vertical scroll bar can be used to scroll through the entire list of packets. Note that CloudShark will load packets from larger files in bursts, using a predictive algorithm to provide seamless iteration.

The middle frame shows a collapsed view of the various layers of the currently selected packet. The hardware layers are listed first, and then the Data Link and Networking layers, and finally the protocol itself. The bottom frame shows the hexadecimal contents of the packet.

When a layer in the middle pane is selected, the data representing that layer will be highlighted in the bottom pane. Individual fields within this layer can be selected further, which reduces the corresponding selection in the bottom pane.

Directly Linking to Capture Files

Capture files can be linked to directly using their CloudShark URL. The URL can be obtained from the address bar in the browser, or from the Sharing tab in the capture file’s info pop-up.

Capture files will only be visible to other CloudShark users and guests if the proper permissions are enabled. Please see the section on sharing capture files for more information.

Specifying Display Filters

CloudShark supports display filters and provides a filter box in the top right corner of the decoder window for this purpose. Display filters can be applied to help identify packets containing specific addresses, ports, protocols, applications, etc. in the capture file.

For example, the following filter displays only ARP and ICMP packets:

arp and icmp

To limit the display to only packets 100 through 499, enter:

frame.number>=100 and frame.number<500

CloudShark supports the same exact filter syntax as Wireshark. See this page for more information on display filter formats and examples.

CloudShark also provides a short-cut for building display filters right from the packet decoder window. Hovering the mouse pointer over a particular protocol field in CloudShark’s decoder window will display a tooltip with the name of the display filter that can be used to create a filter for that field:

Display filters can also be appended to the capture file URL as query strings. This allows capture files to be shared with a display filter automatically applied. For example, to display only FTP packets within a capture file, simply append the string ?filter=ftp to the URL.

When building URLs, be sure to properly encode them using something like the encodeURIComponent() JavaScript function.

String and Hex Search Using Display Filters

CloudShark’s decoder window supports all standard Wireshark display filters. There are many different filters that can be used to search for packets containing certain IP addresses, source or destination ports, protocols, etc.

One particularly useful filter that can be used to find packets containing arbitrary strings or hex data is the frame contains filter.

For example, to find all packets containing the ascii string “google”, apply this display filter (search strings are case sensitive):

frame contains "google"

Note that DNS records use various separators in place of literal dots “.”. As a result, to ensure that DNS packets appear when searching for domain names, the filter frame contains “google” should be used instead of frame contains “google.com”.

To search for a hex string the filter must include colons and omit the double quotes:

frame contains b0:75:0c

There are other variations of the frame contains filter that can be used to narrow the search down even more to specific parts of each frame:

eth contains b0:75:0c
tcp contains "Bob Smith"
udp contains "foo"

Multiple display filters can be concatenated using logical operators. This is helpful when searching for packets of a specific protocol type containing certain strings. For example, to search only http or dns packets containing a text string, apply display filters like this:

http and frame contains "Bob Smith"
dns and frame contains "google"

For more advanced search strings, the filter frame matches [regexp] can also be used with any regular expression.

Zooming In On Capture Files

CloudShark includes a navigation tool in the header which displays a basic graph of the captured network traffic in packets per second. This tool allows the user to zoom in on specific parts of the capture file by dragging the sliders left and right through the graph.

With this tool a user can focus on specific points of interest in the file, such as points where there is a spike or dip in traffic. Note that this feature can also be used in conjunction with the display filter feature to drill down and quickly identify specific packets occurring within a certain portion of the capture file.

Follow Stream

From the decoder window individual TCP and UDP streams can be followed (reassembled). Selecting a packet that is part of TCP or UDP stream will enable the Follow Stream button on the right side of the toolbar. Clicking this button opens the stream associated with the selected packet.

The follow stream window provides a number of useful features, including:

  • A Show only this stream link which re-opens the decode window with a filter applied to display only the selected stream
  • A Filter out this stream link which opens the decode window and displays everything except the selected stream
  • A Open in new window link which will open the follow stream window in a new browser window
  • The ability to view either ASCII or Hex output
  • The ability to separately display each side of the conversation within the selected stream
  • The ability to wrap long-lines, if desired

The Follow Stream button will be disabled if the selected packet is not part of a TCP or UDP stream. For example, the Follow Stream button will be disabled whenever an ARP packet is selected.

Decoder Window Preferences

The decoder window’s columns can be customized by clicking on the Preferences button in the toolbar.

The packet number and annotation columns are fixed. Every other column can be changed by dragging it to or from the list of pre-defined columns. Custom columns based on user specified display filters can also be defined.

For example, to start using the TX Rate, just drag it from the list of additional columns into the list of displayed columns at the top.

To create a custom column showing the SIP User Agent, assign a title and the display filter sip.User-Agent. (Step 1 in the image). The column order can be rearranged by dragging the column labels around (Step 2 in the image). Click Add column to apply this custom column before you save. (Step 3 in the image) The new column will show the value of the display filter on any packets that have the field present. (Step 4 in the image).

See the Wireshark documentation for a full list of display filters.

The decoder window’s time column display can also be modified in the Preferences window to one of the following formats:

  • Seconds since beginning of capture
  • Time of day
  • Date and time of day

The modified column view and time format can be saved for all viewers of the file. In addition a user may choose to permanently save the modified decoder window preferences as their personal default.

Click on the reset button to restore the decoder window preferences to the default system values.

Downloading the Original Capture File

If the Download Original feature is enabled on the appliance, CloudShark will provide a link to download the original capture file to any user with access to the capture file URL. The original file can be downloaded one of two ways:

  • From the decoder window, by clicking on the download link in the header
  • From the file info pop-up, by clicking on the Download Original button in the File Info tab

This feature is useful if additional analysis of the original capture file is required using other tools. In this respect the CloudShark appliance also acts a vault for capture files.

CloudShark admin users can disable access to the original file by setting the “download original” option to disabled in the administration settings section of the Admin Guide.

Users have the option of downloading the original, unmodified capture file, or downloading a new, pcapng file with all CloudShark annotations preserved as pcapng comments. Downloading a new pcapng is only available from the decoder window.

Analysis Tools

CloudShark’s decoder window includes a number of useful analysis tools which c an be accessed by clicking the Analysis Tools button in the top right corner of the toolbar.

CloudShark includes many built-in analysis tools, which are discussed in the sections below. Most of the analysis tools can be opened in a separate window if needed.

Capture File Meta Data

Additional meta information can be associated with all capture files in the CloudShark appliance. This meta information comes in three basic forms:

  • File Tags: Tags are descriptive text strings that are associated with capture files. Their purpose is undefined, so users are able to create their own purposes. Tags are useful for organizing capture files and highlighting specific characteristics.

  • Comments: Comments can be added to capture files as well. Comments are useful for describing a capture file.

  • Annotations: Annotations are essentially individual comments applied to a single packet within a capture file. Annotations are very useful for highlighting and describing specific events within a capture file.

These three types of meta information are discussed in more detail in the sections below.

By default only the admin user and the owner of a particular file can add or modify meta information for that capture file. If the capture file is shared with a specific group and Read/Write permissions are enabled, other group members will have the ability to add or modify meta information for that file. Please see the sharing capture files section for more information.

File Tags

Tags are short descriptive strings associated with capture files. A capture file can have up to 30 tags, comma delimited. Their use is restricted only by the imagination of the user. Tags are useful for aggregation, as an example use. Auto-import directories can be automatically tagged, which performs this aggregation as naturally as searching for the tag. Dates, events, people, places, devices, even vague exclamations such as “weird!” are all viable tag names. It may become more obvious how you personally discover tags to be useful as you begin using CloudShark regularly.

Tags can be added to capture files three different ways:

  • The Info icon/button: The Info icon is displayed to the left of every capture file as a blue circle with an “I” in it. Clicking the Info icon opens the file info pop-up which allows tags to be added or removed from the capture file. Note that the file info pop-up is also available from the decoder window when viewing capture files.

  • Add Tags button: Tags can be added to one or more capture files by selecting them from the capture file index and clicking on the Add Tags button. Note that tags cannot be removed from files using the Add Tags button.

  • Auto-Imports and API Tokens: Tags can also be automatically applied to capture files that are uploaded using the Auto-Import feature or API Tokens. Please see the section on importing files for more information.

When tags are applied to a file they will be displayed in the Tags column in the capture file index. Tags can also be used as criteria when searching for files.

CloudShark admin users also have a special page for bulk editing or removing tags system-wide. See the Admin Guide for more information.

Comments

Comments can be applied to capture files as well. Comments are meant to be a high level description or note applied to the entire file. Comments can be added to individual capture files through the Info pop-up

When a comment is applied to a capture file a small pencil icon will be displayed to the left of the info icon for that capture file in the index.

Comments can also be used as search criteria when searching for files in the capture index. The search feature allows users to search for files with comments containing arbitrary text strings, and also to search for files that either contain or do not contain comments.

Annotations

Annotations are comments applied to individual packets within a capture file. Users can insert annotations to highlight a specific packet or describe a sequence of events in a capture file. Like comments, annotations can also be used as search criteria when searching for files in the capture index. The search feature allows users to search for files that either contain or do not contain annotations.

Annotations support MarkDown syntax and are described in more detail in the post on annotating capture files.

Sharing

Please read the sharing capture files section for more information on the sharing features available in CloudShark.

Pcapng

While CloudShark support for uploading pcapng files has existed since version 1.0, CloudShark 1.6 adds support for importing of pcapng comments, as well as the ability to export CloudShark sessions as pcapng files.

Wireshark version 1.8 uses pcapng as the default file format for saving capture files to disk. This includes the ability to add packet-level annotations to packets within a Wireshark capture, which are saved with the file if the file is saved in pcapng format. Uploading a file with packet-level annotations into a CloudShark session will display these annotations as CloudShark annotations, just as if the user had written the annotations themselves.

These annotations can be added to, edited, or deleted. In order to assist the user in preserving these comments should you want to download the file, you can choose to “Export a new pcapng with CloudShark comments and annotations” after clicking the download link which will generate a new file in pcapng format containing all CloudShark metadata. Alternatively, if users want to grab the original file or maintain the original file format, they can select “Download the original file” from the same window. This file export feature has the additional benefit of being able to take non-pcapng files from other tools and convert them to pcapng through CloudShark.

This feature also works when uploading files using the CloudShark API. Any file-level comments added using the API’s metadata features will overwrite file-level comments in the original file. Packet-level annotations will be preserved.

About CloudShark Appliance

CloudShark Appliance is made by QA Cafe, a technology company based in Portsmouth, NH. Our passion for packet captures has grown out of our other product CDRouter.

Get in touch via our Contact us page or by following us on your favorite service: