InetVis 0.9.3 Manual

documentation and help

Last revision: 2007-11-08

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 Pre-packaged Binary
   3.3. Minimum System Specification
   3.4. Typical Performance

4. Known Issues

5. Building and Developing InetVis
   5.1. Requirements
   5.2. Recommend Development Tools

6. Acknowledgement

7. Disclaimer

8. Contact

1. Description

InetVis - Internet Visualization

version: 0.9.3
release date: 2007/11/07

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 Linux based (but possible to port to Windows or Mac OS X).
• Known to run and compile on Ubuntu and Fedora Core Linux distributions.

3.2. Requirements to run pre-compiled 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 such as libc6).

• libqt3-mt
• lipcap
• libc6
• libstdc++6

3.3. Minimum System Specification

At least a Pentium III class processor with 256MB RAM and a 3-D graphics accelerator supporting OpenGL is recommended.

3.4. Typical Performance

Tested 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

1. Live monitoring not tested extensively and expected to be buggy.
2. Switching numerous times between replay file mode and monitor local mode causes the application to crash with a seg fault.
3. When system reaches full processor usage, replay rate is reduced to a best effort (plays slower than the chosen replay rate).
4. Aggregating traffic would be a major improvement for dealing with production class network traffic.
5. Currently, the application only caters for traffic captured from an Ethernet data link.
6. Axes labels overlap in certain orientations.
7. Error reporting needs refinement (multiple reports, at multiple levels, per error event may occur).
8. 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).
9. Would be nice to have a 'play list' of capture files.
10. Needs GUI controls to choose network interface for live monitoring, rather than always selecting the systems default interface.
11. Lacks a mechanism to select a point an call up detailed textual information, such as the IP addresses, ports, and other such details.
12. IP packets with options are processed, but the options are ignored. Fragmented IP packets are not yet handled and simply dropped by an implicit BPF filter "ip[6:2] & 0x3fff". Refer to RFC 791 for details about the fragment flags and offset field.

...this is why the software is Alpha :)

NB! Help improve the software - 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. Requirements

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

5.2. Recommend Development Tools

The way I did it.

• qtdesigner
• qtassistant
• kate

6. Acknowledgement

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

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

InetVis was initially developed as a student project at Rhodes University. 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. GPL License

InetVis - Internet Visualisation for network traffic analysis.
Copyright (C) 2006 - 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.

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.

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.