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/>`__:

.. code:: bash

    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:

.. code:: bash

    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``:

.. code:: python

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

You can take a look at the packets in ``capfile.packets``:

.. code:: python

    >>> pkt = capfile.packets[0]
    >>> pkt.raw()
    <binary data snipped>
    >>> pkt.timestamp
    1343676707L

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

Automatically decoding layers
-----------------------------

| 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:

.. code:: python

    >>> from pcapfile import savefile
    >>> from pcapfile.protocols.linklayer import ethernet
    >>> from pcapfile.protocols.network import ip
    >>> import binascii
    >>> testcap = open('samples/test.pcap')
    >>> capfile = savefile.load_savefile(testcap, 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 00:11:22:33:44:55 to ff:ee:dd:cc:bb:aa type IPv4
    >>> ip_packet = ip.IP(binascii.unhexlify(eth_frame.payload))
    >>> print ip_packet
    ipv4 packet from 192.168.2.47 to 173.194.37.82 carrying 44 bytes

and this example:

.. code:: python

    >>> from pcapfile import savefile
    >>> testcap = open('samples/test.pcap')
    >>> capfile = savefile.load_savefile(testcap, 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:

.. code:: python

    >>> from pcapfile import savefile
    >>> testcap = open('samples/test.pcap')
    >>> capfile = savefile.load_savefile(testcap, 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

TODO
----

#. write unit tests
#. add ``__repr__`` method that shows all of the values of the fields in
   IP packets
   and Ethernet frames.

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>`__

Contributors
------------

A list of the project's contributors may be found in the AUTHORS file.
