packet

package
v0.0.0-...-9f5628c Latest Latest
Warning

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

 Go to latest Published: Mar 13, 2023 License: LGPL-3.0 Imports: 16 Imported by: 7

Documentation

Overview

Package packet provides gopacket based input functionality for flows.

The packet package contains everything that is needed to process packets efficiently, like gathering those from sources, calculating keys, and concurrent flow table processing based on package flows. Additionally, the base gopacket.Packet interface (Buffer) is extended with additional needed functionality for packet processing.

Buffer

Buffer holds all necessary interfaces for packet processing. Most features will receive this as input. All the standard interfaces from gopacket.Packet are provided (See https://github.com/google/gopacket).

For increased performance, the Link/Network/TransportLayer functions should be used instead of Layer().

Size calculations should use the *Length functions, since those already try to handle all the guess work that is needed, if something goes wrong (e.g. zero ip.length parameter, truncated packets, ...).

Never hold onto one of these buffers, as they are resued for later packets. To store a packet for later, the Copy() function must be used. As soon as this copy is not needed any longer, the Recycle() must be called on this copy. Never every call Recycle() on not-copied packets!. Beware to never Copy() all packets - there is no upper limit on memory consumption and packet allocation requires at least some packets to be reusable.

Index

Constants

This section is empty.

Variables

View Source 
var ErrTimeout = errors.New("Timeout")

ErrTimeout should be returned by sources, if no packet has been observed for some timeout (e.g., 1 second). In this case ci MUST hold the current timestamp

View Source 
var LayerTypeIPv46 = gopacket.RegisterLayerType(1000, gopacket.LayerTypeMetadata{Name: "IPv4 or IPv6"})

LayerTypeIPv46 holds either a raw IPv4 or raw IPv6 packet

Functions

func FilterHelp 

func FilterHelp(which string) error

FilterHelp displays help for a specific filter (see module system in util)

func LabelHelp 

func LabelHelp(which string) error

LabelHelp displays help for a specific label (see module system in util)

func ListFilters 

func ListFilters() ([]util.ModuleDescription, error)

ListFilters returns a list of filters (see module system in util)

func ListKeys 

func ListKeys(w io.Writer)

ListKeys writes a list of keys to w

func ListLabels 

func ListLabels() ([]util.ModuleDescription, error)

ListLabels returns a list of labels (see module system in util)

func ListSources 

func ListSources() ([]util.ModuleDescription, error)

ListSources returns a list of sources (see module system in util)

func NewFlow 

func NewFlow(event flows.Event, table *flows.FlowTable, key string, lowToHigh bool, context *flows.EventContext, id uint64) flows.Flow

NewFlow creates a new flow based on a given event, table, key, context, and flow-id

Depending on the event this will either be a tcp flow, or a standard flow

func RegisterFilter 

func RegisterFilter(name, desc string, new util.ModuleCreator, help util.ModuleHelp)

RegisterFilter registers an filter (see module system in util)

func RegisterKeyPair 

func RegisterKeyPair(a, b int)

RegisterKeyPair registers the given key ids as a source/destination pair

func RegisterLabel 

func RegisterLabel(name, desc string, new util.ModuleCreator, help util.ModuleHelp)

RegisterLabel registers an label (see module system in util)

func RegisterRegexpKey 

func RegisterRegexpKey(name, description string, t KeyType, layer KeyLayer, make MakeKeyFunc) int

RegisterRegexpKey registers a regex key function

func RegisterSource 

func RegisterSource(name, desc string, new util.ModuleCreator, help util.ModuleHelp)

RegisterSource registers an source (see module system in util)

func RegisterStringKey 

func RegisterStringKey(name string, description string, t KeyType, layer KeyLayer, make MakeKeyFunc) int

RegisterStringKey registers a regex key function

func RegisterStringsKey 

func RegisterStringsKey(name []string, description string, t KeyType, layer KeyLayer, make MakeKeyFunc) int

RegisterStringsKey registers a regex key function

func SourceHelp 

func SourceHelp(which string) error

SourceHelp displays help for a specific source (see module system in util)

Types

type Buffer 

type Buffer interface {
	gopacket.Packet
	flows.Event
	// Dot1QLayers returns a slice with all Dot1Q (=VLAN) headers
	Dot1QLayers() []layers.Dot1Q
	//// Functions for querying additional packet attributes
	//// ------------------------------------------------------------------
	// EtherType returns the EthernetType of the link layer
	EtherType() layers.EthernetType
	// Proto returns the protocol field
	Proto() uint8
	// Label returns the label of this packet, if one ones set
	Label() interface{}
	// PacketNr returns the the number of this packet
	PacketNr() uint64
	//// Convenience functions for packet size calculations
	//// ------------------------------------------------------------------
	// LinkLayerLength returns the length of the link layer (=header + payload) or 0 if there is no link layer
	LinkLayerLength() int
	// NetworkLayerLength returns the length of the network layer (=header + payload) or 0 if there is no network layer
	NetworkLayerLength() int
	// PayloadLength returns the length of the payload or 0 if there is no application layer
	PayloadLength() int
	//// Functions for holding on to packets
	//// ------------------------------------------------------------------
	// Copy reserves the buffer, creates a reference, and returns it. Use this if you need to hold on to a packet.
	Copy() Buffer
	// Recycle frees this buffer. WARNING: Use this only on buffers that got returned from Copy!
	Recycle()
	//// Internal interface - don't use (necessa)
	//// ------------------------------------------------------------------
	// SetInfo sets the flowkey and the packet direction
	SetInfo(string, bool)
	// contains filtered or unexported methods
}

Buffer provides the packet interface from gopacket and some additional utility functions

Never hold references to this buffer or modify it, since it will be reused! If you need to keep a packet around for a short time, it must be copied with Copy() and this copy later destroyed with Recycle(). This doesn't actually copy the packet, but increases the refcount. NEVER change the contents of a packet.

func BufferFromLayers 

func BufferFromLayers(when flows.DateTimeNanoseconds, layerList ...SerializableLayerType) Buffer

BufferFromLayers creates a new Buffer for the given time and layers. Used for testing.

type DynamicKeySelector 

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

DynamicKeySelector holds the definition for a flow key function

func MakeDynamicKeySelector 

func MakeDynamicKeySelector(key []string, bidirectional, allowZero bool) (ret DynamicKeySelector)

MakeDynamicKeySelector creates a selector function from a dynamic key definition

func (*DynamicKeySelector) Key 

func (selector *DynamicKeySelector) Key(packet Buffer) (string, bool, bool)

Key computes a key according to the given selector. Returns key, isForward, ok This function _must not_ be called concurrently.

type Engine 

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

Engine holds and manages buffers, sources, filters and forwards packets to the flowtable

func NewEngine 

func NewEngine(plen int, flowtable EventTable, filters Filters, sources Sources, labels Labels) *Engine

NewEngine initializes a new packet handling engine. Packets of plen size are handled (0 means automatic). Packets are read from sources, filtered with filter, and forwarded to flowtable. Labels are assigned to the packets from the labels provider.

func (*Engine) Finish 

func (input *Engine) Finish()

Finish submits eventual partially filled buffers, flushes the packet handling pipeline and waits for everything to finish.

func (*Engine) PrintStats 

func (input *Engine) PrintStats(w io.Writer)

PrintStats writes the packet statistics to w

func (*Engine) Run 

func (input *Engine) Run() (time flows.DateTimeNanoseconds)

Run reads all the packets from the sources and forwards those to the flowtable

func (*Engine) Stop 

func (input *Engine) Stop()

Stop cancels the whole process and stops packet input

type EventTable 

type EventTable interface {
	// EOF expires all the flows in the table at the given point in time with EOF as end reason
	EOF(flows.DateTimeNanoseconds)
	// Print table statistics to the given writer
	PrintStats(io.Writer)
	// contains filtered or unexported methods
}

EventTable represents a flow table that can handle multiple events in one go

func NewFlowTable 

func NewFlowTable(num int, features flows.RecordListMaker, newflow flows.FlowCreator, options flows.FlowOptions, expire flows.DateTimeNanoseconds, selector DynamicKeySelector, autoGC bool) EventTable

NewFlowTable creates a new flowtable with the given record list, a flow creator, flow options, expire time, a key selector, if empty values in the key are allowed and if automatic gc should be used.

num specifies the number of parallel flow tables.

type Filter 

type Filter interface {
	util.Module
	// Matches must return true, if this packet should be used
	Matches(lt gopacket.LayerType, data []byte, ci gopacket.CaptureInfo, n uint64) bool
}

Filter represents a generic packet filter

func MakeFilter 

func MakeFilter(which string, args []string) ([]string, Filter, error)

MakeFilter creates an filter instance (see module system in util)

type Filters 

type Filters []Filter

Filters holds a collection of filters that are tried one after another

func (Filters) Matches 

func (f Filters) Matches(lt gopacket.LayerType, data []byte, ci gopacket.CaptureInfo, n uint64) bool

Matches returns true if this packet matches all filters

type KeyFunc 

type KeyFunc func(packet Buffer, scratch, scratchNoSort []byte) (scratchLen int, scratchNoSortLen int)

KeyFunc is a function that writes the flow key for a single property The key must be written to scratch and the written length returned as scratchLen.

If the property is part of a keypair, it must write to scratch (both parts of the pair must use the same length!) if the result must be ordered for bidirectional flows, and to scratchNoSort (with coresponding length in scratchNoSortLen) if this part must not be ordered. All other properties must use scratch.

type KeyLayer 

type KeyLayer int

KeyLayer specifies on which layer this key resides 

const (
	// KeyLayerNetwork specifies a key on the network layer
	KeyLayerNetwork KeyLayer = iota
	// KeyLayerTransport specifies a key on the transport layer
	KeyLayerTransport
	// KeyLayerApplication specifies a key on the application layer
	KeyLayerApplication
	// KeyLayerLink specifies a key on the link layer
	KeyLayerLink
	// KeyLayerNone specifies a key with no layer
	KeyLayerNone
)

do not change the order here! This is the order for bidirectional flow comparison

type KeyType 

type KeyType int

KeyType specifies the type of this key (unidirectional, source, or destination ) 

const (
	// KeyTypeUnidirectional is a key that mustn't be sorted for bidirectional flows
	KeyTypeUnidirectional KeyType = iota
	// KeyTypeSource is a source key that must be sorted for bidirectional flows
	KeyTypeSource
	// KeyTypeDestination is a destination key that must be sorted for bidirectional flows
	KeyTypeDestination
)

type Label 

type Label interface {
	util.Module
	// GetLabel returns the label for the provided packet
	GetLabel(packet Buffer) (interface{}, error)
}

Label represents a generic packet label

func MakeLabel 

func MakeLabel(which string, args []string) ([]string, Label, error)

MakeLabel creates an label instance (see module system in util)

type Labels 

type Labels []Label

Labels holds a collection of labels that are tried one after another

func (*Labels) GetLabel 

func (l *Labels) GetLabel(packet Buffer) interface{}

GetLabel returns the label of the provided packet

type MakeKeyFunc 

type MakeKeyFunc func(name string) KeyFunc

MakeKeyFunc must return a KeyFunc. Additional

type SerializableLayerType 

type SerializableLayerType interface {
	gopacket.SerializableLayer
	LayerContents() []byte // gopacket.Layer
}

SerializableLayerType holds a packet layer, which can be serialized. This is needed for feature testing

type Source 

type Source interface {
	util.Module
	// ReadPacket reads the next packet from the source.
	// Must return layertype of base layer, binary data, capture info, skipped packets, filtered packets, error
	ReadPacket() (lt gopacket.LayerType, data []byte, ci gopacket.CaptureInfo, skipped uint64, filtered uint64, err error)
	// Stop shuts down the source
	Stop()
}

Source represents a generic packet source

func MakeSource 

func MakeSource(which string, args []string) ([]string, Source, error)

MakeSource creates an source instance (see module system in util)

type Sources 

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

Sources holds a collection of sources that are queried one after another

func (*Sources) Append 

func (s *Sources) Append(a Source)

Append adds source to this source-collection

func (*Sources) Init 

func (s *Sources) Init()

Init initializes the sources

func (*Sources) ReadPacket 

func (s *Sources) ReadPacket() (lt gopacket.LayerType, data []byte, ci gopacket.CaptureInfo, skipped uint64, filtered uint64, err error)

ReadPacket reads a single packet from the current packet source. In case the current source is empty, it switches to the next one.

func (*Sources) Stop 

func (s *Sources) Stop()

Stop all packet sources

type Stats 

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

Stats holds number of packets, skipped packets, and filtered packets

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.