trace

package
v0.0.0-...-33a618f Latest Latest
Warning

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

Go to latest
Published: Dec 15, 2020 License: BSD-3-Clause Imports: 9 Imported by: 1

Documentation

Overview

WARNING: This package is experimental and may change without notice!

The trace package provides support for analyzing and storing the data gathered by the pcap package.

Index

Constants

View Source
const (
	Version     = "beta-0-0-1"       // For compatibility checks if PktTrace changes
	ArchiveType = "application/gzip" // MIME type for archived PktTrace results
)

Variables

View Source
var (
	ErrApplicationLayerHeader = errors.New("Application Layer Header Error")
	ErrBadPort                = errors.New("No ports match")
	ErrEmptyData              = errors.New("Data is empty")
	ErrFlowMismatch           = errors.New("Flows do not match")
	ErrNetworkLayerHeader     = errors.New("Network Layer Header Error")
	ErrSameSrcDstPorts        = errors.New("Src and Dst ports match")
	ErrTCPSeqMissing          = errors.New("TCP Sequnce Number Missing")
	ErrTransportLayerHeader   = errors.New("Transport Layer Header Error")
)

Package errors

View Source
var (
	ApplicationLayer = 3       // Index for OSI Application Layer in Pkt.Headers
	ServerSrcPort    = int(80) // Expected server source port
)

Functions

func ACKCapacity

func ACKCapacity(d []*pkt.Packet, pm map[uint32]*pkt.Packet) ([]time.Duration, []float64, error)

ACKCapacity calculates the IP capacity in bits per nanosecond for every monotonically increasing ACK in d. The resulting slices are suitable for use as the x and y values in a plot of IP capacity vs. time.

func ACKThroughput

func ACKThroughput(d []*pkt.Packet) ([]time.Duration, []float64, error)

ACKThroughput calculates the throughput in bits per nanosecond for every monotonically increasing ACK in d. The resulting slices are suitable for use as the x and y values in a plot of throughput vs. time.

func ACKTimes

func ACKTimes(d []*pkt.Packet) ([]time.Time, []uint32, error)

ACKTimes returns the timestamps and ACK sequence numbers that are strictly increasing within d.

func GetHTTPTraffic

func GetHTTPTraffic(d []*pkt.Packet) map[string]*HTTPExchange

GetHTTPTraffic parses the packets in d []*pkt.Packet looking for *pkt.HttpHdr, When one is found we slice that section of the packets to create a new HTTPExchange. The result is a map of httpHdr.RequestURI to HTTPExchange. The Data for the HTTPExchange is a slice backed by the same array as d.

For now this is not designed to work well on pipelined responses.

func GetIPTraffic

func GetIPTraffic(d []*pkt.Packet) map[string]*IPFlow

GetIPTraffic separates all the IP traffic in the slice of pkt.Packet into their respective flows. The resulting map of IPFlow are keyed by the string of their IPTuple.

func GetTCPTraffic

func GetTCPTraffic(d []*pkt.Packet) map[string]*TCPFlow

GetTCPTraffic separates all the TCP traffic in the slice of pkt.Packet into their respective flows. The resulting map of TCPFlow are keyed by the string of their TCPTuple.

func SEQCapacity

func SEQCapacity(d []*pkt.Packet, pm map[uint32]*pkt.Packet) ([]time.Duration, []float64, error)

SEQCapacity calculates the IP capacity in bits per nanosecond for every monotonically increasing sequence number in d. The resulting slices are suitable for use as the x and y values in a plot of IP capacity vs. time.

func SEQThroughput

func SEQThroughput(d []*pkt.Packet) ([]time.Duration, []float64, error)

SEQThroughput calculates the throughput in bits per nanosecond for every monotonically increasing sequence number in d. The resulting slices are suitable for use as the x and y values in a plot of throughput vs. time.

func SEQTimes

func SEQTimes(d []*pkt.Packet) ([]time.Time, []uint32, error)

SeqTimes returns the timestamps and sequence numbers that are strictly increasing within d.

func TCPContextDump

func TCPContextDump(d []*pkt.Packet, l, c int) ([]string, int, error)

TCPContextDump provides debugging information for d[l] with up to c lines of context. The int is the index of the d[l] within the context. A result that returns with an error may still have d[l] with partial context.

func TCPDataDump

func TCPDataDump(d []*pkt.Packet) ([]string, error)

TCPDataDump provides text debugging information for all the TCP packets in d. A result that returns with an error may still have partial information up to the packet that caused the error.

Types

type HTTPExchange

type HTTPExchange struct {
	TCPTuple    *TCPTuple     // The source and destination addresses
	ReqHTTPHdr  *pkt.HttpHdr  // The HTTP request Header
	RespHTTPHdr *pkt.HttpHdr  // The HTTP response Header
	Data        []*pkt.Packet // The array of packets
	Resp        int           // The beginning of the HTTP response
}

A HTTPExchange makes working with HTTP data easier. The TCPTuple will have the Dst set as the address that is sending the request, and the Src as the address that responds. The data will always have the packet that contains the request as Data[0].

For now this is not designed to work well on pipelined responses.

func NewHTTPExchange

func NewHTTPExchange(d []*pkt.Packet, respIndex int) (*HTTPExchange, error)

NewHTTPExchange creates and returns a HTTPExchange with the given packet data. it is important that the packet with the HTTP request be present in d[0], and it is assumed that the ACK for the last packet of response is in d[len(d)-1]. Having a valid respIndex for the first packet of the response containing the HTTP response header will speed this up, if it is not valid (<0 if unknown) then this method will search for it. The Data for the HTTPExchange is a slice backed by the same array as d.

This method does not check the rest of d to make sure that the packets are in fact part of this transfer, so only pass what should be used.

func (*HTTPExchange) GetTCPFlow

func (e *HTTPExchange) GetTCPFlow() *TCPFlow

GetTCPFlow returns a new *TCPFlow using the packet data in the HTTPExchange.

func (*HTTPExchange) String

func (e *HTTPExchange) String() string

String returns the ReqHTTPHdr.RequestURI for use as a non-robust key.

type IPFlow

type IPFlow struct {
	IPTuple   *IPTuple      // The source and destination addresses
	Data      []*pkt.Packet // The array of packets
	StartTime time.Time     // Time of the first packet
	EndTime   time.Time     // Time of the last packet
	Bytes     int64         // Number of bytes from the source to the destination
	PLBytes   int64         // Number of payload bytes from the source to the destination
}

An IPFlow makes working with IP data easier.

func (*IPFlow) AddPacket

func (f *IPFlow) AddPacket(p *pkt.Packet) error

AddPacket updates the meta data for a IPFlow and saves a reference to the pkt.Packet. This assumes the packet addresses have been checked and the IP flow matches (it does not check for matching addresses).

type IPTuple

type IPTuple struct {
	Src net.IP // The source IP address
	Dst net.IP // The destination IP address
}

An IPTuple encapsulates the source and destination address for analysing IP packet traces.

func NewIPTuple

func NewIPTuple(p *pkt.Packet) (*IPTuple, error)

NewIPTuple constructs an IPTuple from the information in the pkt.Packet headers. This assumes that the packet is an IP packet.

func (*IPTuple) Equal

func (t *IPTuple) Equal(x *IPTuple) bool

Equal returns true if t and x have the same source and destination IP address.

func (*IPTuple) String

func (t *IPTuple) String() string

String returns a serialized form of an IPTuple suitable for use as a key.

type MetaPcap

type MetaPcap struct {
	Device   string   // The device used for packet capture
	FileName string   // The filename used for reading a pcap savefile
	Snaplen  int32    // Specifies the maximum number of bytes to capture
	Promisc  int32    // 0->false, 1->true
	Timeout  int32    // ms
	Filters  []string // track filters applied to the capture
}

A MetaPcap is a copy of the meta data from pcap.Pcap. We keep this copy separate so that it cannot be executed by mistake, and by not depending on the system's C libraries it can be more portable.

type PktTrace

type PktTrace struct {
	Version    string         // For trace version compatibility issues
	LibVersion string         // The version of libpcap being used
	Date       time.Time      // Date the trace was created
	Notes      string         // Meta data not otherwise specified
	MetaPcap   *MetaPcap      // Meta data from pcap.Pcap
	Stats      *stat.Stat     // Capture stats straight from libpcap
	Data       *[]*pkt.Packet // The headers of the captured packets
}

A PktTrace combines the pkt.Packet data with meta data so that it can be archived and analyzed.

func PktTraceFromArchive

func PktTraceFromArchive(r io.Reader) (*PktTrace, error)

PktTraceFromArchive reads a given gzip compressed gob encoded PktTrace. This is the standard format for storing a PktTrace to a file.

func (*PktTrace) Archive

func (t *PktTrace) Archive(w io.Writer) error

Archive saves a PktTrace to a gzip compressed gob encoded file.

type TCPFlow

type TCPFlow struct {
	TCPTuple       *TCPTuple              // The source and destination addresses
	Data           []*pkt.Packet          // The array of packets
	StartTime      time.Time              // Time of the first packet
	EndTime        time.Time              // Time of the last packet
	SrcFirstSeq    uint32                 // The first seq number in the flow
	DstFirstSeq    uint32                 // The first seq number in the flow
	SrcFirstAckSeq uint32                 // The first ACK seq number in the flow
	DstFirstAckSeq uint32                 // The first ACK seq number in the flow
	SrcBytes       int64                  // Number of application bytes Src->Dst
	DstBytes       int64                  // Number of application bytes Dst->Src
	SrcPLBytes     int64                  // Number of IP payload bytes Src->Dst
	DstPLBytes     int64                  // Number of IP payload bytes Dst->Src
	SrcWireBytes   int64                  // Number of off the wire bytes Src->Dst
	DstWireBytes   int64                  // Number of off the wire bytes Dst->Src
	SrcPktCnt      int64                  // Number of packets Src->Dst
	DstPktCnt      int64                  // Number of packets Dst->Src
	SrcData        []*pkt.Packet          // An array of packets Src->Dst
	DstData        []*pkt.Packet          // An array of packets Dst->Src
	SrcDataMap     map[uint32]*pkt.Packet // A map of seq to packets Src->Dst
	DstDataMap     map[uint32]*pkt.Packet // A map of seq to packets Dst->Src
}

A TCPFlow makes working with TCP data easier.

func NewTCPFlow

func NewTCPFlow(d []*pkt.Packet, t *TCPTuple) *TCPFlow

NewTCPFlow filters the packet in d by t.MatchFlow and returns the resulting TCPFlow for analysis.

func (*TCPFlow) AddData

func (f *TCPFlow) AddData(d []*pkt.Packet)

AddData will call f.AddPacket for each packet in d where f.TCPTuple.MatchFlow is true. This is a faster way to create a TCPFlow if you know you are only interested in the TCP traffic for a single TCPTuple.

func (*TCPFlow) AddPacket

func (f *TCPFlow) AddPacket(p *pkt.Packet) error

AddPacket updates the meta data for a TCPFlow and saves a reference to the pkt.Packet. This assumes the packet addresses have been checked and the TCP flow matches (it does not check for matching addresses).

func (*TCPFlow) Analyze

func (f *TCPFlow) Analyze() (*TCPFlowStats, error)

Analyze computes the aggregate packet-level data for a TCPFlow. This does not take into account packets that may have been dropped by the pcap trace and the analysis of such traces will be less accurate than those without any missing packets.

type TCPFlowStats

type TCPFlowStats struct {
	DstDupAck    int    // Total number of duplicate Dst ACKs
	DstLoss      int    // Number retransmitted Dst packets
	DstLossBytes uint32 // Number of retransmitted Dst bytes
	DstOrder     int    // Number of out-of-order Dst packets
	DstOther     int    // Number of other non-normal Dst packets
	SrcDupAck    int    // Total number of duplicate Src ACKs sent
	SrcLoss      int    // Number retransmitted Src packets
	SrcLossBytes uint32 // Number of retransmitted Src bytes
	SrcOrder     int    // Number of out-of-order Src packets
	SrcOther     int    // Number of other non-normal Src packets
}

Aggregate packet-level data for a TCPFlow. This is usually returned from a call to TCPFlow.Analysis().

func TCPFlowAnalysis

func TCPFlowAnalysis(d []*pkt.Packet, t *TCPTuple) (*TCPFlowStats, error)

Analysis computes the aggregate packet-level data for a TCPFlow. This does not take into account packets that may have been dropped by the pcap trace and the analysis of such traces will be less accurate than those without any missing packets.

type TCPTuple

type TCPTuple struct {
	Src *net.TCPAddr // The source IP address
	Dst *net.TCPAddr // The destination IP address
}

A TCPTuple encapsulates the source and destination address for analysing TCP/IP packet traces.

func NewTCPTuple

func NewTCPTuple(p *pkt.Packet) (*TCPTuple, error)

NewTCPTuple constructs a TCPTuple from the information in the pkt.Packet headers. This assumes that the packet is a TCP/IP packet.

func (*TCPTuple) Equal

func (t *TCPTuple) Equal(x *TCPTuple) bool

Equal returns true if t and x have the same source and destination IP:Port address.

func (*TCPTuple) MatchFlow

func (t *TCPTuple) MatchFlow(x *TCPTuple) bool

MatchFlow returns t.Equal || t.REqual

func (*TCPTuple) REqual

func (t *TCPTuple) REqual(x *TCPTuple) bool

REqual returns true if both source addresses match both destination addresses.

func (*TCPTuple) String

func (t *TCPTuple) String() string

String returns a serialized form of a TCPTuple suitable for use as a key.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL