Module pcap

pcap module - A wrapper for Packet Capture library

This module intends to be an exhaustive wrapper for the well known
Packet Capture library. It defines 3 new objects:
- pcap object which is a wrapper for `pcap_t' of PCAP library
- pcap_dumper object which is a wrapper for `pcap_dumper_t' of PCAP library
- bpf_program object which is a wrapper for `struct bpf_program' used in
  PCAP library

In this module, each PCAP library function whose generic prototype is
`type pcap_func (pcap_t *, ...)' is implemented as a method (named `func')
of pcap object whose returned value is (Python) `type' (None if `type'
is `void'). For example, the function `int pcap_inject (pcap_t * p,
const void * buf, size_t size)' becomes the method `pcap.inject(<str>)',
the latter returning a (Python) integer.

Similary, each PCAP library function whose generic prototype is
`type pcap_func (pcap_dumper_t *, ...)' is implemented as a method
(named `func') of pcap_dumper object.
Note that a pcap_dumper object cannot be created directly. It can only be
created using the `dump_open()' method of a pcap object instance.

As above, each PCAP library function whose generic prototype is
`type pcap_func (struct bpf_program *, ...)' is implemented as a method
(named `func') of bpf_program object.
Note that a bpf_program object cannot be created directly. It can only be
created using the `compile()' method of a pcap object instance.

All remaining PCAP library functions are implemented as methods of pcap
module.

Module defines only one exception: `error'. This exception is accompagnied
with a string value which is generally the error message generated by
PCAP library (if not, it is a pcap module specific error).

Module pcap defines some constants such as AF_INET, AF_INET6, AF_LINK,
DLT_* and PCAP_* (see html documentation for more details).

See PCAP library documentation (http://www.tcpdump.org) for more details.
Also, you can have a look in subdirectory `examples' you will find in the
distribution.

Classes

[hide private]

bpf_program
bpf_program object is a wrapper for the type `struct bpf_program_t' used in PCAP library.

error

pcap
pcap object is a wrapper for the type `pcap_t' defined in PCAP library.

pcap_dumper
pcap_dumper object is a wrapper for the type `pcap_dumper_t' defined in PCAP library.

Functions

[hide private]

pcap object

pcap_create(source=...)
pcap_create() create a live capture handle.

<int>

pcap_datalink_name_to_val(name)
pcap_datalink_name_to_val() get the link-layer header type value corresponding to a header type name.

<str>

pcap_datalink_val_to_description(dlt)
pcap_datalink_val_to_description() get a short description for a link-layer header type value.

<str>

pcap_datalink_val_to_name(dlt)
pcap_datalink_val_to_name() get a name for a link-layer header type value.

None

pcap_dump(user, h, sp)
pcap_dump() write a packet to a capture file.

(device, device,...)

pcap_findalldevs()
pcap_findalldevs() get a list of capture devices.

pcap object

pcap_fopen_offline(fp)
pcap_fopen_offline() open a saved capture file for reading.

<str>

pcap_lib_version()
pcap_lib_version() get the version information for libpcap.

<str>

pcap_lookupdev()
pcap_lookupdev() find the default device on which to capture.

{'net': <str>, 'mask': <str>}

pcap_lookupnet(device)
pcap_lookupnet() find the IPv4 network number and netmask for a device.

pcap object

pcap_open_dead(linktype=..., snaplen=...)
pcap_open_dead() open a fake pcap_t for compiling filters or opening a capture for output.

pcap object

pcap_open_live(device, snaplen=..., promisc=..., to_ms=...)
pcap_open_live() open a device for capturing.

pcap object

pcap_open_offline(fname)
pcap_open_offline() open a saved capture file for reading.

Variables

[hide private]

AF_INET = 2

AF_INET6 = 10

AF_LINK = 17

DLT_ARCNET = 7

DLT_ARCNET_LINUX = 129

DLT_ATM_RFC1483 = 11

DLT_C_HDLC = 104

DLT_EN10MB = 1

DLT_FDDI = 10

DLT_FRELAY = 107

DLT_IEEE802 = 6

DLT_IEEE802_11 = 105

DLT_IEEE802_11_RADIO = 127

DLT_IP_OVER_FC = 122

DLT_LINUX_IRDA = 144

DLT_LINUX_LAPD = 177

DLT_LINUX_SLL = 113

DLT_LOOP = 108

DLT_LTALK = 114

DLT_NULL = 0

DLT_PFLOG = 117

DLT_PPP = 9

DLT_PPP_ETHER = 51

DLT_PPP_SERIAL = 50

DLT_PRISM_HEADER = 119

DLT_RAW = 12

DLT_SLIP = 8

PCAP_D_IN = 1

PCAP_D_INOUT = 0

PCAP_D_OUT = 2

PCAP_IF_LOOPBACK = 1

PCAP_SNAPLEN_DFLT = 65535

__package__ = None

Function Details

[hide private]

pcap_create(source=...)

pcap_create() create a live capture handle. It is a wrapper for corresponding pcap_create() Packet Capture library routine.

When pcap_create() is executed without argument, packets are are captured from all interfaces. See PCAP library documentation for more details.

Returns: pcap object

pcap_datalink_name_to_val(name)

pcap_datalink_name_to_val() get the link-layer header type value corresponding to a header type name. It is a wrapper for corresponding pcap_datalink_name_to_val() Packet Capture library routine.

Returns: <int>

pcap_datalink_val_to_description(dlt)

pcap_datalink_val_to_description() get a short description for a link-layer header type value. It is a wrapper for corresponding pcap_datalink_val_to_description() Packet Capture library routine.

Returns: <str>

pcap_datalink_val_to_name(dlt)

pcap_datalink_val_to_name() get a name for a link-layer header type value. It is a wrapper for corresponding pcap_datalink_val_to_name() Packet Capture library routine.

Returns: <str>

pcap_dump(user, h, sp)

pcap_dump() write a packet to a capture file. It is a wrapper for corresponding pcap_dump() Packet Capture library routine.

Argument `user' must be a pcap dumper object (as returned by `dump_open()' method of a pcap object instance). Argument `h' must be a Python dictionary which is a wrapper for `struct pcap_pkthdr' defined in PCAP library. See `loop()' documentation for a description of this dictionary. Last argument `sp' is a (raw) string.

Returns: None

pcap_findalldevs()

pcap_findalldevs() get a list of capture devices. It is a wrapper for
corresponding pcap_findalldevs() Packet Capture library routine.

A device is a dictionary of the following format:
  {'name': <str>, # 'eth0' for example
   'description': <str> or None,
   'addresses': (address, address,...) # see below
   'flags': <int> # interface flags
  }
and where an address is in turn a dictionary of the following format:
  {'addr': (<str>, <int>), # (address, address family)
   'netmask': (<str>, <int>) or None, # (address, address family)
   'broadaddr': (<str>, <int>) or None, # (address, address family)
   'dstaddr': (<str>, <int>) or None, # (address, address family)
  }
Note: address family may have the values pcap.AF_INET, pcap.AF_INET6
or pcap.AF_LINK (on Linux, pcap.AF_LINK is the constant AF_PACKET
and on FreeBSD, pcap.AF_LINK is the constant AF_LINK.

Returns: (device, device,...)

pcap_fopen_offline(fp)

pcap_fopen_offline() open a saved capture file for reading. It is a wrapper for corresponding pcap_fopen_offline() Packet Capture library routine.

Argument `fp' is a file object. File object `fp' should have been opened with mode `wb'.

Returns: pcap object

pcap_lib_version()

pcap_lib_version() get the version information for libpcap. It is a wrapper for corresponding pcap_lib_version() Packet Capture library routine.

Returns: <str>

pcap_lookupdev()

pcap_lookupdev() find the default device on which to capture. It is a wrapper for corresponding pcap_lookupdev() Packet Capture library routine.

Returns: <str>

pcap_lookupnet(device)

pcap_lookupnet() find the IPv4 network number and netmask for a device. It is a wrapper for corresponding pcap_lookupnet() Packet Capture library routine.

Returns: {'net': <str>, 'mask': <str>}

pcap_open_dead(linktype=..., snaplen=...)

pcap_open_dead() open a fake pcap_t for compiling filters or opening a capture for output. It is a wrapper for corresponding pcap_open_live() Packet Capture library routine.

Default values for `linktype' and `snaplen' are respectively `pcap.DLT_EN10MB' and `pcap.PCAP_SNAPLEN_DFLT' (65535)

Returns: pcap object

pcap_open_live(device, snaplen=..., promisc=..., to_ms=...)

pcap_open_live() open a device for capturing. It is a wrapper for corresponding pcap_open_live() Packet Capture library routine.

Default values for `snaplen', `promisc' and `to_ms' are respectively `pcap.PCAP_SNAPLEN_DFLT' (65535), 0 and 0.

Note: `pcap.pcap_open_live()' and `pcap.pcap()' (pcap object contructor) are equivalent.

Returns: pcap object

pcap_open_offline(fname)

pcap_open_offline() open a saved capture file for reading. It is a wrapper for corresponding pcap_open_offline() Packet Capture library routine.

Returns: pcap object