pdb.tex

The Packet Debugger, pdb is a program which allows people to work with packet streams as if they we

\documentclass[11pt]{article}
\usepackage{codespelunking}
\usepackage[pdftex]{hyperref}
\title{Packet Debugger}
\author{George V. Neville-Neil}
\begin{document}
\maketitle

\section{Introduction}

The Packet Debugger, \emph{pdb} is a program which allows people to
work with packet streams as if they were working with a source code
debugger. Users can list, inspect, modify, and retransmit any packet
from captured files as well as work with live packet capture.

Installing \program{pdb} is covered in the text file,
\file{INSTALLATION}, which came with this package.  The code is under
a BSD License and can be found in the file \file{COPYRIGHT} in the
root of this package.

\emph{Note: You will very likely need root or sudo access in order to
write packets directly to a network interface, or read them directly
from it.  If you don't understand this note, then please talk to your
local systems or network administrator before trying to use
\program{pdb} to read and write raw packets.}

\section{A Quick Tour}

For the impatient this section is a 5 minute intro to using the packet
debugger.

Create a \program{pcap} file with \program{tcpdump},
\program{ethereal}, \program{wireshark} or another program of your
choosing.  Now load the \program{pcap} file into \program{pdb} as
shown in Figure~\ref{fig:tour}.  Figure~\ref{fig:tour} will serve as
our only figure throughout this section.  You said you were impatient,
didn't you?

\begin{figure}
  \centering
\begin{verbatim}
minion ? sudo src/pdb.py -f tests/test.out -i en0
Welcome to PDB version Alpha 0.1.
For a list of commands type 'help <rtn>'
For help on a command type 'help command <rtn>'
pdb> help

Documented commands (type help <topic>):
========================================
break     delete  list  next  print  run   set   unload
continue  info    load  prev  quit   send  show

pdb> print

0: <Ethernet: src: '\x00\r\x022{\x9c', dst: '\xff\xff\xff\xff\xff\xff', type: 2054>
  <ARP: spa: 3538819329L, tpa: 3538819566L, hln: 6, pro: 2048, 
        sha: '\x00\r\x022{\x9c', pln: 4, hrd: 1, 
        tha: '\x00\x00\x00\x00\x00\x00', op: 1>

pdb> list
0: <Ethernet: src: '\x00\r\x022{\x9c', dst: '\xff\xff\xff\xff\xff\xff', type: 2054>
  <ARP: spa: 3538819329L, tpa: 3538819566L, hln: 6, pro: 2048, sha: '\x00\r\x022{\x9c', pln: 4, hrd: 1, tha: '\x00\x00\x00\x00\x00\x00', op: 1>

1: <Ethernet: src: '\x00\r\x022{\x9c', dst: '\xff\xff\xff\xff\xff\xff', type: 2054>
  <ARP: spa: 3538819329L, tpa: 3538819566L, hln: 6, pro: 2048, sha: '\x00\r\x022{\x9c', pln: 4, hrd: 1, tha: '\x00\x00\x00\x00\x00\x00', op: 1>

2: <Ethernet: src: '\x00\x17\xf2\xe8\x9a*', dst: '\x00\r\x022{\x9c', type: 2048>  <IPv4: hlen: 5, protocol: 6, src: 167844872, tos: 0, dst: 1074628338, ttl: 64, length: 105, version: 4, flags: 2, offset: 0, checksum: 47703, id: 37679>
  <TCP: reset: 6, reserved: 0, sequence: 3630104920L, ack: 1, checksum: 1430, offset: 8, syn: 12, urgent: 0, window: 65535, push: 3, ack_number: 4015249839L, dport: 993, sport: 49616, fin: 0, urg_pointer: 0>
  <Data: payload: 13461827120112604152439673499521091613012183756744016516126079577203641068557009167112742657168772916671786032510888690444211521996639179562876754643964994L>

3: <Ethernet: src: '\x00\r\x022{\x9c', dst: '\x00\x17\xf2\xe8\x9a*', type: 2048>  <IPv4: hlen: 5, protocol: 6, src: 1074628338, tos: 0, dst: 167844872, ttl: 55, length: 425, version: 4, flags: 2, offset: 0, checksum: 40686, id: 46680>
  <TCP: reset: 6, reserved: 0, sequence: 4015249839L, ack: 1, checksum: 64954, offset: 8, syn: 12, urgent: 0, window: 33304, push: 3, ack_number: 3630104973L, dport: 49616, sport: 993, fin: 0, urg_pointer: 0>
  <Data: payload: 5833012640182693830740685309126491793183699354072300151259887449111900223013072262057228427952454204363050124163974701919320231039714257186439729648731796984576895640540827156034249534186268294777905353058494442547381940092005934427977703939254077088072230177882319530193101444049370977201335185290558235492941608468398296242021852705546280494168148714793243111271446226387129752233141276928172956761542113121601891159734015928292135298305526284694598441895919668354893368028440796272596499459637782160160949364173180847632982338355958973538673335692826303060143533552478348684067153096055484460618734949540202673143664114973333257350640273968888301032870000789426742409723456522916256773251706805158210497890950688880528440262065433000898705974667973316825759346425343593300497289668031645087750161623693418694103031553157333595341291066305455733262705911384454726321109625967822889228309280197390940855905815302395040621413L>

[NOTE: Packets 4 through 9 removed for brevity]

pdb> run
pdb> quit
Bye
\end{verbatim}
  \caption{Quick starting \program{pdb}}
  \label{fig:tour}
\end{figure}

The first thing to do when you start a new program is to ask for help,
and \program{pdb} is no different in this respect.  The complete
command set is described in the built in help system.  You can ask for
help on each command as well, but that is not shown in this section.

\program{pdb} attempts to at very much like a well known debugger and
so, if you're a programmer, you're very likely to recognize many of
the commands.

In our example we've loaded the test data used to test this program,
\file{test.out}.  Each file or set of packets is part of a stream, and
in this example we have one stream, which was loaded from
\file{test.out}.  We are currently at position 0 in the stream, the
beginning.  We can print the packet at the current position with the
\verb|print| command, as shown in the example.  What we see is an
Ethernet packet, containing an ARP request.  We can also list all the
packets in the stream, up to a user configured limit.  The \verb|list|
command shows, by default, 10 packets, including the one at your
current position and the following 9.  To play back a stream over the
interface selected at start up the \verb|run| command is used.  If you
pick an Ethernet interface at start up, as we did with \verb|en0|, then
the packet stream will be sent over that interface.  To see the
packets you're playing back you can run \program{tcpdump} or a similar
packet capture program, to see the packets coming from \program{pdb}.


\section{Starting \program{pdb}}

In order to start a debugging session you will need either a
pre-recorded \program{pcap} file or a network interface to work with,
and possibly both.  The command line arguments to \program{pdb} are
relatively simple and are shown in
Figure~\ref{fig:pdb-command-line-arguments}.

\begin{figure}
  \centering
\begin{verbatim}
usage: pdb.py [options]

options:
  -h, --help            show this help message and exit
  -f FILENAME, --file=FILENAME
                        pcap file to read
  -i INTERFACE, --interface=INTERFACE
                        Network interface to connect to.
\end{verbatim}
  \caption{\program{pdb} command line arguments}
  \label{fig:pdb-command-line-arguments}
\end{figure}

The \verb|-f| or \verb|--file| switch supplies a path and file name to
\program{pdb} which it will then attempt to load into the program.  If
no \verb|-i| or \verb|--interface| argument is supplied then the user
can only read packets from the file.  Other files and interfaces may
be opened from the command line, see Sections

Once \program{pdb} has started you will see the command prompt, shown
in Figure~\ref{fig:command-prompt}.

\begin{figure}
  \centering
\begin{verbatim}
pdb>
\end{verbatim}
  \caption{Command Prompt}
  \label{fig:command-prompt}
\end{figure}

At this point \program{pdb} is awaiting your commands.

\subsection{Working with the Command Line}
\label{sec:working-with-the-command-line}

The Command Line Interpreter (CLI) in \program{pdb} is implemented
using the \class{Cmd} module in Python, which in turn uses the popular
\program{readline} package.  What all of that means is that you have 
fairly rich, built in command line functions, including the ability to
repeat, edit, and complete command lines.  We are not going to
reproduce all of the documentation on \program{readline} in this
section but will give a brief introduction to what the CLI provides.
If you have worked with any modern Unix shell, i.e. bash, tcsh, etc.,
you will be quite comfortable using the \program{pdb} CLI.

As with any other command line your cursor waits at the prompt for
your input.  You can ask for \verb|help| which will give you a list of
commands to choose from, and you can ask for help on a particular
command, which will explain the command itself.  When you are entering
characters on the command line you can use a few special keys to edit
the text you have already entered, and these keys are listed in
Table~\ref{tab:cli-editing-keys}.

\begin{table}
  \centering
  \begin{tabular}{|l|l|}
    \hline
    Ctrl-b & Back up one character\\
    \hline
    Ctrl-f & Move forward one character\\
    \hline
    Ctrl-a & Move to the beginning of the line\\
    \hline
    Ctrl-e & Move to the end of the line\\
    \hline
    Enter & Ask \program{pdb} to execute the command\\
    \hline
    Tab & Complete command\\
    \hline
  \end{tabular}
  \caption{CLI Editing Keys}
  \label{tab:cli-editing-keys}
\end{table}

Command completion is the ability of the CLI to guess, based on a few
characters, what command you're trying to give to it.  Using the Tab
key frequently is a good way to avoid typing too much or making typing
mistakes.  If the CLI is unable to understand the command you're trying
to complete it will tell you, by either going no further in the
command line when you type Tab, or by giving you a set of choices of
possible commands to complete.  Pressing Tab when there is no text
after the command prompt will give you a list of all the available
commands.  Some commands also have completion based on the data you
are trying to work with, such as a list of streams, and these special
cases are covered in sections \ref{sec:cmd-run}, \ref{sec:cmd-info},
\ref{sec:cmd-list}, and \ref{sec:cmd-set}, which cover the commands
that have completion.

Unlike a Unix shell exiting by the Ctrl-d (EOF) key is not supported,
though the program can be halted using Ctrl-c.  We strongly recommend
using the \verb|quit| command to exit the program.

\section{Command Reference}
\label{sec:command-reference}

All of the commands implemented in \program{pdb} are covered in this
section and its subsequent sub-sections.

\subsection{help}
\label{sec:help}

The help command prints out the available topics for help.  
\begin{figure}[h]
  \centering
\begin{verbatim}
pdb> help

Documented commands (type help <topic>):
========================================
break     delete  info  load  prev   quit  send  show  
continue  help    list  next  print  run   set   unload
\end{verbatim}
  \caption{Help on all commands}
  \label{fig:help-all-example}
\end{figure}

To get help on a specific command type \verb|help command| where
\verb|command| is one of the commands listed when you ask for help on
its own.

\begin{figure}[h]
  \centering
\begin{verbatim}
pdb> help help
help [command]
print out the help message, with [command] get help on that comamnd
\end{verbatim}
  \caption{Help on the help command}
  \label{fig:help-on-help-example}
\end{figure}

\subsection{quit}
\label{sec:quit}

Quit the program.  All program state is lost.  In the next version it
will be possible to save the state of your streams before exiting.

\begin{figure}[h]
  \centering
\begin{verbatim}
pdb> quit
Bye
localhost ? 
\end{verbatim}
  \caption{Quit Command}
  \label{fig:quit-example}
\end{figure}

\subsection{Loading and Saving Streams}
\label{sec:loading-and-saving-streams}

Each of the commands in this section works on a stream, which is the
basic unit on which pdb operates.

\subsubsection{load}
\label{sec:cmd-load}

Read a new stream from a file, or open a network connection.
Currently only \program{pcap} files are supported by the \verb|load|
command.  

\begin{figure}[h]
  \centering
\begin{verbatim}
pdb> load filename tests/test.out
\end{verbatim}
  \caption{Load example}
  \label{fig:load-example}
\end{figure}

\subsubsection{unload}
\label{sec:cmd-unload}

Unload a previously loaded stream.  If a numeric argument is supplied
then \program{pdb} will attempt to unload that stream.  To see all the
currently loaded streams use the \verb|info| command, discussed in
Section~\ref{sec:cmd-info}.

\begin{figure}[h]
  \centering
\begin{verbatim}
pdb> unload
\end{verbatim}
  \caption{Unload command}
  \label{fig:unload-example}
\end{figure}

\subsection{Inspecting a Stream}
\label{sec:inspecting-a-stream}

Once a \class{Stream} is loaded into \program{pdb} you will want to
work with it in various ways.  In this section we cover all the