pypcapfile
==========

pypcapfile is a pure Python library for handling libpcap savefiles. 


Installing
----------

The easiest way to install is from 
[pypi](http://pypi.python.org/pypi/pypcapfile/):

    sudo pip install pypcapfile

Note that for pip, the package name is `pypcapfile`; in your code you will need to 
import `pcapfile`.

Alternatively, you can install from source. Clone the repository, and run setup.py with 
an install argument:

    git clone git://github.com/kisom/pypcapfile.git
    cd pypcapfile
    ./setup.py install

This does require the Python [distutils](http://docs.python.org/install/) to be
installed.


Introduction
------------

The core functionality is implemented in pcapfile.savefile:

>>> from pcapfile import savefile
>>> sf = savefile.load_savefile('test.pcap', verbose=True)
[+] attempting to load test.pcap
[+] found valid header
[+] loaded 11 packets
[+] finished loading savefile.
>>> print sf
big-endian capture file version 2.4
snapshot length: 65535
linklayer type: LINKTYPE_ETHERNET
number of packets: 11
>>>

You can a look at the packets in sf.packets:
>>> pkt = sf.packets[0]
>>> pkt.raw()
<binary data snipped>
>>> pkt.timestamp
1343676707L
>>>

Right now there is very basic support for Ethernet frames and IPv4 packet 
parsing. 

The `layers` argument to `load_savefile` determines how many layers to 
decode; the default value of 0 does no decoding, 1 will load only the link 
layer, etc... For example, with no decoding:

>>> from pcapfile import savefile
>>> from pcapfile.protocols.linklayer import ethernet
>>> from pcapfile.protocols.network import ip
>>> import binascii
>>> capfile = savefile.load_savefile('samples/test.pcap', verbose=True)
[+] attempting to load samples/test.pcap
[+] found valid header
[+] loaded 3 packets
[+] finished loading savefile.
>>> eth_frame = ethernet.Ethernet(capfile.packets[0].raw())
>>> print eth_frame
ethernet from 68:a8:6d:01:7f:b6 to 00:18:e7:dc:e5:01 type IPv4
>>> ip_packet = ip.IP(binascii.unhexlify(eth_frame.payload))
>>> ip_packet.src, ip_packet.dst, ip_packet.v, ip_packet.len
('192.168.2.47', '173.194.37.82', 4, 64)

and this example:
>>> from pcapfile import savefile
>>> capfile = savefile.load_savefile('samples/test.pcap', layers=1, verbose=True)
[+] attempting to load samples/test.pcap
[+] found valid header
[+] loaded 3 packets
[+] finished loading savefile.
>>> print capfile.packets[0].packet.src
00:11:22:33:44:55
>>> print capfile.packets[0].packet.payload
<hex string snipped>

and lastly:
>>> from pcapfile import savefile
>>> capfile = savefile.load_savefile('samples/test.pcap', layers=2, verbose=True)
>>> print capfile.packets[0].packet.payload
ipv4 packet from 192.168.2.47 to 173.194.37.82 carrying 44 bytes

The IPv4 module (`ip`) currently only supports basic IP headers, i.e. it 
doesn't yet parse options or add in padding.

The interface is still a bit messy.


Future planned improvements
---------------------------

* IP option handling
* IPv6 support
* TCP and UDP support
* ARP support


See also
--------

* The project's [PyPi page](http://pypi.python.org/pypi/pypcapfile).
* The project's [Sphinx](http://sphinx.pocoo.org/) 
[documentation on PyPI](http://packages.python.org/pypcapfile/)
* The [libpcap homepage](http://www.tcpdump.org)
