InetVis 0.9.5 Manual

documentation and help

Last revision: 2007-11-21

Contents

1. Description
   1.1. Concept
   1.2. Input
      1.2.1. Supported Protocols
   1.3. Plotting Scheme
   1.4. Features

2. Usage
   2.1. Command Line
   2.2. User Interface and Controls
      2.2.1. Control Panel
      2.2.2. InetVis Display
         2.2.2.1. Navigation via Mouse Controls
         2.2.2.2. Navigation via Keyboard Controls
         2.2.2.3. Other Keyboard Controls
      2.2.3. Plotter Settings Dialogue
      2.2.4. Reference Frame Settings Dialogue
   2.3. Usage Notes
      2.3.1. Tool tips as Helpful Hints
      2.3.2. Applying Settings
      2.3.3. Setting the Home Network Range Before Playback
      2.3.4. Setting Address Ranges with CIDR Notation
      2.3.5. Recording
         2.3.5.1. Record to Capture File
         2.3.5.2. Taking an Image Snapshot
         2.3.5.3. Dumping Rendered Frames to Image Files
         2.3.5.4. Location of Recorded Files
      2.3.6. Administrator Privileges

3. Requirements and Performance
   3.1. Operating Platform
   3.2. Requirements to Run Linux Binary
   3.3. Requirements to Run Windows Binary
   3.4. Minimum System Specification
   3.5. Typical Performance

4. Known Issues
   4.1 Stability and Performance
   4.2 Limitations and Feature Wish List

5. Building and Developing InetVis
   5.1. Build Requirements for Linux (Ubuntu/Debian)
   5.2. Build Requirements for Windows
   5.3. Recommend Development Tools

6. Acknowledgement

7. Disclaimer

8. Contact

1. Description

InetVis - Internet Visualization

version: 0.9.5
release date: 2007/11/21

InetVis is a 3-D scatter-plot visualization for network traffic. It's more or less like a media player, but for network traffic. At the moment its just an academic toy for reviewing packet capture files, but may be useful in other endeavours. For example, InetVis has been used to verify and critique the accuracy of scan detection algorithms in the Snort IDS and Bro IDS.

1.1. Concept

The original source of inspiration for InetVis is the "The Spinning Cube of Potential Doom" (by Stephen Lau). Whilst many other network visualizations employ lines as a metaphor for connection, the 3-D scatter-plot of points proves to scale well with larger volumes of data. The visualization makes network scanning and port scanning readily evident as horizontal and vertical lines respectively. InetVis offers numerous extensions that enhance the original basic concept (see 1.4. Features). For a description of "The Spinning Cube of Potential Doom" see:

• www.nersc.gov/security/TheSpinningCube.html.

1.2. Input

InetVis visualizes packet captures of network traffic using Libpcap to either

• capture live traffic from the default interface, or
• replay traffic from a pcap file.

Tcpdump, Wireshark and Snort are examples of applications can use the Libpcap file format.

• www.tcpdump.org
• www.ethereal.com
• www.snort.org

1.2.1. Supported Protocols

• Ethernet IPv4 based traffic with TCP, UDP and ICMP protocols.

1.3. Plotting scheme

• Destination address (home network) plotted along blue x-axis (horizontal).
• Source address (external Internet range) plotted along red z-axis (depth).
• Ports (TCP and UDP) plotted along green y-axis (vertical).
• ICMP traffic plotted below TCP/UDP cube grey/white ICMP plane.

1.4. Features

• Adjustable replay position to seek through the traffic capture files.
• Variable playback speed (time scaling), from as slow as 0.001x (1 ms/s), or as fast as 86400x (1 day/s).
• Variable time frame/window to view events for the past 100 ms up to 5 years.
• Transparent decay of events - points fade as they age (with respect to the time window).
• New events are highlighted by pulsing once (a momentarily bulge of the point).
• Filtering capability via BPF filter expressions (as used in Libpcap and Tcpdump).
• Various colour schemes for colouring points and adjustable point size.
• Setting the data ranges and scaling down into sub-domain IP addresses (destination and source) as well as port ranges to view a subset of the traffic data.
• Adjustable logarithmic plot for stretching out lower port range where, in general, most TCP/UDP traffic occurs.
• Various reference frame controls, i.e. toggling visibility of axes, markers, transparent grid lines, labels, and background colour.
• Orthographic and perspective projection modes.
• Immersive navigation - scaling (zooming), translating (moving) and rotating.
• Record single snapshot image, or dump all image frames (useful for manually encoding video clips).
• Record output back to pcap binary file format, for further detailed analysis with other applications (e.g. Tcpdump, Ethereal and Snort).

2. Usage

2.1. Command Line

./inetvis

2.2. User Interface and Controls

The display pane and control panel are in separate windows, with a plotter settings dialogue and reference frame settings dialogue accessed via the 'view' menu of the control panel

2.2.1. Control Panel

• main menu to open files, set mode (monitor local host or replay file), or to access other dialogues (view).
• Replay position controls.
• Playback and replay speed controls.
• Recording controls.
• Time window controls (Historic View).
• Filter.
• Task-bar reports the number of packets currently in the buffer.

2.2.2. InetVis Display

The visualization display pane.

2.2.2.1. Navigation via Mouse Controls.

• Holding left button and moving rotates.
• Holding right button and moving translates along x and y (horizontally and vertically respectively).
• Rotating scroll wheel translates along z (depth).
• Holding middle button and moving zooms.

2.2.2.2. Navigation via Keyboard Controls.

• 'Arrow Keys' to rotate.
• 'Ctrl' + 'Arrow Keys' to translate (x and y).
• 'Alt' + 'UP Arrow Key' or 'Down Arrow Key' to translate (z).
• '+' and '-' to scale (zoom).
• 'Home' or 'Ctrl+f' to reset view to front on (up z axis).
• 'End' to view from back (down z axis).
• 'Ctrl+l' to view from left side (up x axis).
• 'Ctrl+r' to view from right (down x axis).
• 'Ctrl+t' to view from top (down y axis).
• 'Ctrl+b' to view from below (up y axis).

2.2.2.3. Other Keyboard Controls

• 'f' to toggle full screen.
• 'Esc' to escape full screen.
• 'p' to bring up Plotter Settings Dialogue.
• 'r' to bring up Reference Frame Settings Dialogue.
• 'c' to bring up Control Panel Dialogue.
• 'Ctrl+H' to hide home address range (addresses replaced with obscuring labels).

2.2.3. Plotter Settings Dialogue

• Set the destination home network range (or drill down into it).
• Set the source Internet range (drill down into a domain).
• Set the port range (drill down into a port range).
• Set linear or logarithmic plotting for ports.
• Set colour mapping, toggle transparent decay, and set background colour (black or white).
• Set point size, point bulging (highlight new events), and toggle point smoothing (rounded points).

2.2.4. Reference Frame Settings Dialogue

• Set projection mode (Orthographic or perspective).
• Toggle visibility of reference frame axes and markers.
• Toggle visibility and transparency of grid lines.
• Set number of divisions along x, y, and z for markers and grid lines.
• Toggle text labels (time, axes ranges, frame rate).

2.3. Usage Notes

2.3.1. Tool tips as Helpful Hints

Majority of the controls, buttons and fields in the GUI provide tool tips to help explain their function and usage. Tool tips can be seen by hovering the mouse cursor over the GUI component in question.

2.3.2. Applying Settings

Many of the settings are grouped together and require the user to click the apply button (button with a tick icon) once they are ready to apply the new settings.

2.3.3. Setting the Home Network Range Before Playback

After opening a file, set the home network address (in Plotter Settings dialogue) to scale the data along the blue axis - otherwise all traffic is rendered in a narrow single band with respect to the x-axis. A 'guess' button can help infer this home network range by checking the destination addresses contained within the file. In the case of monitoring the local network interface (live packet capture), the application will automatically retrieve the home network address from Libpcap.

2.3.4. Setting Address Ranges with CIDR Notation

Setting the address ranges entails using 'dots-slash' (CIDR) notation to specify network sub-domains. For example 192.168.0.0/24 is the network with address 192.168.0.0, subnet mask 255.255.255.0, giving the network range 192.168.0.0 to 192.168.0.255. The number after the slash represents the number of bits in the subnet mask. Thus the octet classed network masks are:

• Class A = 255.0.0.0 = /8
• Class B = 255.255.0.0 = /16
• Class C = 255.255.255.0 = /24

Values other than /8, /16 and /24 are trickier as they involve bits in between the four octets of a 32 bit IP address. The Plotter Settings dialogue has a field below the dots-slash edit boxes that show the range and subnet mask to help as guide. For bits added on to a full octet (i.e. /8+x or /16+x or /24+x), the following octet in the mask will have the value:

For example, 146.231.120/20 has subnet mask 255.255.248.0 and represents 8 class C networks in the range 146.231.120.0 to 146.231.127.255.

2.3.5. Recording

All three record methods, recording to capture file, taking a single image snapshot, or dumping rendered frames to image files, can be used simultaneously and used in conjunction with playback.

2.3.5.1. Record to Capture File

2.3.5.2. Taking an Image Snapshot

2.3.5.3. Dumping Rendered Frames to Image Files

InetVis can record rendered frames to image files. Frame record sessions work much the same way as capture file record sessions. Whilst the record button with the film symbol is on, the application dumps each frame to an image file, and stops when the button is toggled off. For each frame, a raw copy of the image buffer is copied into an uncompressed image file (.ppm format). Consequently, recording image frames uses up a large amount of disk space at a rapid rate and can degrade the applications performance - setting the window to a smaller resolution will help reduce the performance hit.

During frame recording, the timing is fixed to produce frames suitable for encoding video clips at 25 frames per second (fps). Even if, whilst recording, it appears that playback is degraded to less than 25 fps, the timing between each frames is calculated with respect to the data in the file and according to the replay speed. Therefore, when the frame capture files are encoded to video a clip at 25 frames per second, the video clip has the correct timing and replay speed while despite the recording process appearing slower. As a consequence, playback of some video clips may appear faster that the original recording.

2.3.5.4. Location of Recorded Files

Recording back to capture file, taking a snapshot image, or dumping frames, creates a directory hierarchy relative to the InetVis running directory.

• recorded/frames
• recorded/pcaps
• recorded/snapshots

Within these directories, sub-directory structures follow and should be self explanatory. Some file and directory names include numeric timestamps of the form yyyymmdd-hhMMsszzz (where MM is minutes and zzz milliseconds) - the timestamps refer to timestamps in the capture file (or live capture).

2.3.6. Administrator Privileges

Administer privileges are required to open a live capture interface of the systems network interface.

3. Requirements and Performance

3.1. Operating Platform

• Currently actively developed and supported on Linux. Known to run and compile on Ubuntu, Debian and Fedora Core.
• Ported to Windows, but the windows port remains largely untested. The OpenGL performance in the windows port appears inferior to Linux.
• It is possible to port to Mac OS X, but a port has not been attempted.

3.2. Requirements to Run Linux Binary

The binary is compiled for Linux based systems and optimised for the Intel i686 processor. It requires OpenGL, the Libpcap packet capture library and Trolltech Qt GUI API (as well as other system libraries that should be present by default, such as libc6).

• libqt4
• libqt4-qt3support
• lipcap
• libc6
• libstdc++6

3.3. Requirements to Run Windows Binary

The binary is compiled for the Intel 686 processor. It relies on WinPCap and Trolltech Qt 4. The DLLs of these are included with the distribution. The DLLs for WinPCap are the Windows NT/2000/XP/2003 compatible version. Standard system C libraries as well as winsock2 are required and should be present on the system by default.

3.4. Minimum System Specification

At least a Pentium III class processor with 256MB RAM and a 3-D graphics accelerator supporting OpenGL is recommended. While InetVis may work with on-board video cards, poor performance and limited OpenGL support is a typical drawback.

3.5. Typical Performance

Tested on Ubuntu 7.04 with Intel Core2 (6300) 1.86 GHz CPU, 2GB RAM, GeForce 7600GS (256MB) graphics card.

• The application takes a best effort approach to rendering 25 frames a second. Once rendering at less than 25 frames per second, playback becomes slower than the chosen replay rate.
• During playback, handles 100MB capture file with about 500,000 packets at 25 frames per second.
• During playback, handles 200MB capture file with about 2,000,000 packets at about 5 FPS.
• When paused, handles 600MB capture file with about 6,000,000 packets at 8 FPS using an OpenGL display list optimisation.
• When recording frames, expect a significant performance hit due to heavy file I/O.

4. Known Issues

4.1 Stability and Performance

1. Target frame rate is intentionally caped at 25 frames per second. The achieved frame rate is usualy a little slower and when the system reaches full processor usage, the replay rate is reduced to a best effort (plays slower than the chosen replay rate).
2. Large capture files take a while to load while the GUI remains unresponsive. Similarly, some interactions require reloading the capture file, which, if not cached in RAM, will be applied with noticeable delay.
3. Attempting to view too many packets may exhaust system memory. The system will just about halt if the application starts running from swap space. To improve InetVis should (yet to be implemented) have a memory cap set and warn the user while automatically decreasing the time window to limit memory usage.
4. Unspecified GUI problems may exist due to a port from Qt3 to Qt4
5. The windows port is quick and dirty, not tested extensively and expected to be buggy. The pre-packaged version is very basic with no proper installer and the required DLLs are lumped with the exe file. The WinPcap DLLs are for Windows NT/XP/2K/2003 (windows 9x requires a different version of packet.dll).
6. Live monitoring is not tested extensively and expected to be buggy. Switching numerous times between replay file mode and monitor local may cause the application to crash with a memory segmentation bug.
7. Pre-compiled binaries are only for Intel Processors. No tests have been performed with AMD.

Limitations and Feature Wish List

1. The option to aggregate packet traffic into flows would be a major improvement for dealing with production class network traffic.
2. Additional colour schemes would be nice. Furthermore, colour legends would help assist the users interpreting colours.
3. Axes labels overlap in certain orientations.
4. The reference frame and grid lines could be made more intelligent by dynamically scaling according to the data ranges chosen and only applying grids on the panes of the cube in the background.
5. Error reporting needs refinement (multiple reports and obscure references to code functions might be experienced).
6. InetVis lacks a mechanism to select a point an call up detailed textual information, such as the IP addresses, ports, and other such details.
7. The multi-window GUI is a little awkward and could do with re-factoring into a single integrated window with semi-transparent control overlays. This would allow the user to toggle controls and while making changes see the effect on the visualisation in the background.
8. Would be nice to have a 'play list' of capture files that can be queued for replay.
9. Proper file indexing, instead of re-reading the file from the start would improve manipulations (such as setting the filter, setting the domain/port ranges, changing the colour scheme, and so forth).
10. Needs GUI controls to choose network interface for live monitoring, rather than always selecting the systems default interface.
11. Currently, the application only caters for traffic captured from an Ethernet data link.
12. IP packets with options are processed, but the options are ignored. Fragmented IP packets are not yet handled and simply drooped by an implicit BPF filter "ip[6:2] & 0x3fff". Refer to RFC 791 for details about the fragment flags and offset field.
13. The ability to integrate IDS alerts, or at least scan detection alerts from an IDS, would be awesome.

InetVis is still regarded as a pre-production.

NB! Help improve InetVis - please report bugs (including tYpos and spelin errors in this doc), user experience, and feature wishes (see 8. Contact).

5. Building and Developing InetVis

Written with c++, OpenGL, the Qt API, and Libpcap.

5.1. Build Requirements for Linux (Ubuntu/Debian)

• essential build utilities like:
  • g++
  • libc-dev
  • libstdc++-dev
  • make
• libpcap-dev (old versions may cause compile errors)
• libgl1-mesa-dev
• libqt4-dev
• qt4-dev-tools

5.2. Build Requirements for Windows

• Qt4 Windows Open Source Edition and MinGW (the open source / free way).
• OR Qt4 Windows and Visual Studio.
• WinPCap

5.3. Recommend Development Tools

The way I did it.

• qtdesigner-qt3.
• qtassistant.
• kate with make plugin.

Perhaps a better way:

• qtdesigner-qt4.
• qtassistant.
• Eclipse C++ with Qt4 integration.

6. Acknowledgement

Based on the "The Spinning Cube of Potential Doom", by Stephen Lau

• www.nersc.gov/security/TheSpinningCube.html.

Special thanks to Barry Irwin (project supervisor), and Shaun Bangay (Graphics honours course lecture of 2005). Their instruction and input has made this project possible.

7. Disclaimer

USE AT YOUR OWN RISK! InetVis is an academic project and not fit for commercial use. Whilst every effort has been made to confirm that the software accurately represents network traffic as intended, the developer(s) make no guarantee that it is error free. The source code is fairly contrived and convoluted as features where hastily hacked in as needed. Review of the code will be non-(non-non-trivial).

8. Contact

Jean-Pierre van Riel
email: jp _dot_ vanriel _at_ gmail _dot_ com
website: http://research.ict.ru.ac.za/G02V2468/

9. License

9.1. GPL License, Version 2

InetVis - Internet Visualisation for network traffic analysis.
Copyright (C) 2005 - 2007, Jean-Pierre van Riel

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.

9.2. Software Dependencies and Licensing

InetVis makes use of Libpcap/WinPcap, Qt and OpenGL. The open source version of Qt by Trolltech is licensed under the GPL, version 2 (as shown above). According to SGI, use of the OpenGL API requires no license. Libpcap is distributed under the BSD license. WinPcap, the windows derivative of libpcap is licensed by CASE Technologies. As required, the respective licenses are shown below.

9.2.1. Libpcap License

License: BSD

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
3. The names of the authors may not be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.

9.2.2. WinPcap License