pcapio

package
v1.7.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 29, 2024 License: BSD-3-Clause Imports: 13 Imported by: 0

Documentation

Index

Constants

View Source 
const NgNoValue64 = math.MaxUint64

NgNoValue64 is a placeholder for an empty numeric 64 bit value.

View Source 
const PacketBlockHeaderLen = 28

Variables

This section is empty.

Functions

func NewErrInvalidPcap 

func NewErrInvalidPcap(err error) error

Types

type BlockType 

type BlockType int
const (
	TypePacket BlockType = iota
	TypeSection
	TypeInterface
)

type ErrInvalidPcap 

type ErrInvalidPcap struct {
	// contains filtered or unexported fields
}

func (*ErrInvalidPcap) Error 

func (e *ErrInvalidPcap) Error() string

func (*ErrInvalidPcap) Is 

func (e *ErrInvalidPcap) Is(target error) bool

func (*ErrInvalidPcap) Unwrap 

func (e *ErrInvalidPcap) Unwrap() error

type NgInterface 

type NgInterface struct {
	// Name is the name of the interface. This value might be empty if this option is missing.
	Name string
	// Comment can be an arbitrary comment. This value might be empty if this option is missing.
	Comment string
	// Description is a description of the interface. This value might be empty if this option is missing.
	Description string
	// Filter is the filter used during packet capture. This value might be empty if this option is missing.
	Filter string
	// OS is the operating system this interface was controlled by. This value might be empty if this option is missing.
	OS string
	// LinkType is the linktype of the interface.
	LinkType layers.LinkType
	// TimestampResolution is the timestamp resolution of the packets in the pcapng file belonging to this interface.
	TimestampResolution NgResolution
	// TimestampResolution is the timestamp offset in seconds of the packets in the pcapng file belonging to this interface.
	TimestampOffset uint64
	// SnapLength is the maximum packet length captured by this interface. 0 for unlimited
	SnapLength uint32
	// Statistics holds the interface statistics
	Statistics NgInterfaceStatistics
	// contains filtered or unexported fields
}

NgInterface holds all the information of a pcapng interface.

func (NgInterface) Resolution 

func (i NgInterface) Resolution() gopacket.TimestampResolution

Resolution returns the timestamp resolution of acquired timestamps before scaling to NanosecondTimestampResolution.

type NgInterfaceStatistics 

type NgInterfaceStatistics struct {
	// LastUpdate is the last time the statistics were updated.
	LastUpdate time.Time
	// StartTime is the time packet capture started on this interface. This value might be zero if this option is missing.
	StartTime time.Time
	// EndTime is the time packet capture ended on this interface This value might be zero if this option is missing.
	EndTime time.Time
	// Comment can be an arbitrary comment. This value might be empty if this option is missing.
	Comment string
	// PacketsReceived are the number of received packets. This value might be NoValue64 if this option is missing.
	PacketsReceived uint64
	// PacketsReceived are the number of received packets. This value might be NoValue64 if this option is missing.
	PacketsDropped uint64
}

NgInterfaceStatistics hold the statistic for an interface at a single point in time. These values are already supposed to be accumulated. Most pcapng files contain this information at the end of the file/section.

type NgReader 

type NgReader struct {
	*peeker.Reader
	// contains filtered or unexported fields
}

NgReader wraps an underlying bufio.NgReader to read packet data in pcapng.

func NewNgReader 

func NewNgReader(r io.Reader) (*NgReader, error)

NewNgReader initializes a new writer, reads the first section header, and if necessary according to the options the first interface.

func (*NgReader) InterfaceDescriptor 

func (r *NgReader) InterfaceDescriptor(block []byte) (NgInterface, error)

func (*NgReader) Offset 

func (r *NgReader) Offset() uint64

func (*NgReader) Packet 

func (r *NgReader) Packet(block []byte) ([]byte, nano.Ts, layers.LinkType, error)

Packet returns the captured portion of a packet from an enhanced packet block returned by Read() (i.e., with BlockType equal to TypePacket) beginning with the link-layer header. It also extracts the capture timestamp and link layer type and returns those values along with the packet. If an error is encountered, zero values are returned for the three values. PCAP-NG simple packet types aren't supported yet (we presume this type of trace is rare and does not fit our use case here as these traces do not include capture timestamps and the point here is to pull our ranges of packets from a large pcap based on timestamp). We also do not support the original deprecated PCAP-NG packet format but could add support if users request this (it would only be because old pcaps with this deprecated format are sitting around).

func (*NgReader) Read 

func (r *NgReader) Read() ([]byte, BlockType, error)

readPacketHeader looks for a packet (enhanced, simple, or packet) and parses the header. If an interface descriptor, an interface statistics block, or a section header is encountered, those are handled accordingly. All other block types are skipped. New block types must be added here.

func (*NgReader) SectionHeader 

func (r *NgReader) SectionHeader(block []byte) NgSectionInfo

func (*NgReader) SetWarningHandler 

func (r *NgReader) SetWarningHandler(warner Warner)

type NgResolution 

type NgResolution uint8

NgResolution represents a pcapng timestamp resolution

func (NgResolution) Binary 

func (r NgResolution) Binary() bool

Binary returns true if the timestamp resolution is a negative power of two. Otherwise NgResolution is a negative power of 10.

func (NgResolution) Exponent 

func (r NgResolution) Exponent() uint8

Exponent returns the negative exponent of the resolution.

func (NgResolution) ToTimestampResolution 

func (r NgResolution) ToTimestampResolution() (ret gopacket.TimestampResolution)

ToTimestampResolution converts an NgResolution to a gopaket.TimestampResolution

type NgSectionInfo 

type NgSectionInfo struct {
	MajorVersion uint16
	MinorVersion uint16
	// Hardware is the hardware this file was generated on. This value might be empty if this option is missing.
	Hardware string
	// OS is the operating system this file was generated on. This value might be empty if this option is missing.
	OS string
	// Application is the user space application this file was generated with. This value might be empty if this option is missing.
	Application string
	// Comment can be an arbitrary comment. This value might be empty if this option is missing.
	Comment string
}

NgSectionInfo contains additional information of a pcapng section

func (NgSectionInfo) Version 

func (n NgSectionInfo) Version() string

type PcapReader 

type PcapReader struct {
	*peeker.Reader
	LinkType layers.LinkType
	// contains filtered or unexported fields
}

PcapReader implements the Reader interface to read packet data in PCAP format. See https://gitlab.com/wireshark/wireshark/-/wikis/Development/LibpcapFileFormat for information on the file format.

We currenty read v2.4 file format with nanosecond and microsecond timestamp resolution in little-endian and big-endian encoding.

If the PCAP data is gzip compressed it is transparently uncompressed by wrapping the given io.Reader with a gzip.Reader.

func NewPcapReader 

func NewPcapReader(r io.Reader) (*PcapReader, error)

NewPcapReader returns a new reader object, for reading packet data from the given reader. The reader must be open and header data is read from it at this point. If the file format is not supported an error is returned. 

// Create new reader:
f, _ := fs.Open("/tmp/file.pcap")
defer f.Close()
r, err := NewReader(f)
data, info, err := r.Read()

func (*PcapReader) Offset 

func (r *PcapReader) Offset() uint64

func (*PcapReader) Packet 

func (r *PcapReader) Packet(block []byte) ([]byte, nano.Ts, layers.LinkType, error)

func (*PcapReader) Read 

func (r *PcapReader) Read() ([]byte, BlockType, error)

func (*PcapReader) Resolution 

func (r *PcapReader) Resolution() gopacket.TimestampResolution

Resolution returns the timestamp resolution of acquired timestamps before scaling to NanosecondTimestampResolution.

func (*PcapReader) SetSnaplen 

func (r *PcapReader) SetSnaplen(newSnaplen uint32)

SetSnaplen sets the snapshot length of the capture file.

This is useful when a pcap file contains packets bigger than then snaplen. Pcapgo will error when reading packets bigger than snaplen, then it dumps those packets and reads the next 16 bytes, which are part of the "faulty" packet's payload, but pcapgo thinks it's the next header, which is probably also faulty because it's not really a packet header. This can lead to a lot of faulty reads.

The SetSnaplen function can be used to set a bigger snaplen to prevent those read errors.

This snaplen situation can happen when a pcap writer doesn't truncate packets to the snaplen size while writing packets to file. E.g. In Python, dpkt.pcap.Writer sets snaplen by default to 1500 (https://dpkt.readthedocs.io/en/latest/api/api_auto.html#dpkt.pcap.Writer) but doesn't enforce this when writing packets (https://dpkt.readthedocs.io/en/latest/_modules/dpkt/pcap.html#Writer.writepkt). When reading, tools like tcpdump, tcpslice, mergecap and wireshark ignore the snaplen and use their own defined snaplen. E.g. When reading packets, tcpdump defines MAXIMUM_SNAPLEN (https://github.com/the-tcpdump-group/tcpdump/blob/6e80fcdbe9c41366df3fa244ffe4ac8cce2ab597/netdissect.h#L290) and uses it (https://github.com/the-tcpdump-group/tcpdump/blob/66384fa15b04b47ad08c063d4728df3b9c1c0677/print.c#L343-L358).

For further reading:

func (*PcapReader) Snaplen 

func (r *PcapReader) Snaplen() uint32

Snaplen returns the snapshot length of the capture file.

func (*PcapReader) String 

func (r *PcapReader) String() string

Reader formatter

func (*PcapReader) TsFromHeader 

func (r *PcapReader) TsFromHeader(hdr []byte) nano.Ts

func (*PcapReader) Version 

func (r *PcapReader) Version() string

type Reader 

type Reader interface {
	Read() ([]byte, BlockType, error)
	Packet([]byte) ([]byte, nano.Ts, layers.LinkType, error)
	Offset() uint64
}

Reader is an interface for reading data blocks from a pcap, either a legacy pcap or a next-gen pcap. The Read method returns blocks of data that are one of: a pcap file header (TypeSection), a pcap packet including the capture header (TypePacket), a pcap-ng section block (TypeSection), a pcap-ng interface block (TypeInterface), or a pcap-ng packet block (TypePacket). For TypePacket, the capture timestamp and the link-layer type of the packet is indicated in the Info return value.

func NewReader 

func NewReader(r io.Reader) (Reader, error)

NewReader returns a Reader by trying both pcap and pcap-ng formats.

func NewReaderWithWarnings 

func NewReaderWithWarnings(r io.Reader, warner Warner) (Reader, error)

NewReaderWithWarnings returns a Reader by trying both pcap and pcap-ng formats and arranges for warning messages to be sent over the given channel. Different pcap implementations can have out-of-spec peculiarities that can be tolerated so we send warnings and try to keep going.

type Warner 

type Warner interface {
	Warn(msg string) error
}

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.