libbpfgo

package module
Version: v0.1.1 Latest Latest
Warning

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

Go to latest
Published: Jun 15, 2021 License: Apache-2.0 Imports: 9 Imported by: 7

README

libbpfgo


libbpfgo is a Go library for working with Linux's eBPF. It was created for Tracee, our open source Runtime Security and eBPF tracing tools written in Go. If you are interested in eBPF and it's applications, check out Tracee on Github: https://github.com/aquasecurity/tracee.

libbpfgo is built around libbpf - the standard library for interacting with eBPF from userspace, which is a C library maintained in Linux upstream. We have created libbpfgo as a thin Go wrapper around libbpf.

Installing

libbpfgo is using CGO to interop with libbpf and will expect to be linked with libbpf at run or link time. Simply importing libbpfgo is not enough to get started, and you will need to fulfill the required dependency in one of the following ways:

  1. Install the libbpf as a shared object in the system. Libbpf may already be packaged for you distribution, if not, you can build and install from source. More info here.
  2. Embed libbpf into your Go project as a vendored dependency. This means that the libbpf code is statically linked into the resulting binary, and there are no runtime dependencies. Tracee takes this approach and you can take example from it's Makefile.

Concepts

libbpfgo tries to make it natural for Go developers to use, by abstracting away C technicalities. For example, it will translate low level return codes into Go error, it will organize functionality around Go struct, and it will use channel as to let you consume events.

In a high level, this is a typical workflow for working with the library:

  1. Compile your bpf program into an object file.
  2. Initialize a Module struct - that is a unit of BPF functionality around your compiled object file.
  3. Load bpf programs from the object file using the BPFProg struct.
  4. Attach BPFProg to system facilities, for example to "raw tracepoints" or "kprobes" using the BPFProg's associated functions.
  5. Instantiate and manipulate BPF Maps via the BPFMap struct and it's associated methods.
  6. Instantiate and manipulate Perf Buffer for communicating events from your BPF program to the driving userspace program, using the RingBuffer struct and it's associated objects.

Example

// initializing
import bpf "github.com/aquasecurity/libbpfgo"
...
bpfModule := bpf.NewModuleFromFile(bpfObjectPath)
bpfModule.BPFLoadObject()

// maps
mymap, _ := bpfModule.GetMap("mymap")
mymap.Update(key, value)

// ring buffer
rb, _ := bpfModule.InitRingBuffer("events", eventsChannel, buffSize)
rb.Start()
e := <-eventsChannel

Please check our github milestones for an idea of the project roadmap. The general goal is to fully implement/expose libbpf's API in Go as seamlessly as possible.

Learn more

Documentation

Index

Constants

View Source
const (
	BPFProgTypeUnspec uint32 = iota
	BPFProgTypeSocketFilter
	BPFProgTypeKprobe
	BPFProgTypeSchedCls
	BPFProgTypeSchedAct
	BPFProgTypeTracepoint
	BPFProgTypeXdp
	BPFProgTypePerfEvent
	BPFProgTypeCgroupSkb
	BPFProgTypeCgroupSock
	BPFProgTypeLwtIn
	BPFProgTypeLwtOut
	BPFProgTypeLwtXmit
	BPFProgTypeSockOps
	BPFProgTypeSkSkb
	BPFProgTypeCgroupDevice
	BPFProgTypeSkMsg
	BPFProgTypeRawTracepoint
	BPFProgTypeCgroupSockAddr
	BPFProgTypeLwtSeg6Local
	BPFProgTypeLircMode2
	BPFProgTypeSkReuseport
	BPFProgTypeFlowDissector
	BPFProgTypeCgroupSysctl
	BPFProgTypeRawTracepointWritable
	BPFProgTypeCgroupSockopt
	BPFProgTypeTracing
	BPFProgTypeStructOps
	BPFProgTypeExt
	BPFProgTypeLsm
	BPFProgTypeSkLookup
)

Variables

This section is empty.

Functions

func GetUnsafePointer

func GetUnsafePointer(data interface{}) (unsafe.Pointer, error)

Types

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

type BPFMap

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

func (*BPFMap) DeleteKey

func (b *BPFMap) DeleteKey(key interface{}) error

func (*BPFMap) GetMaxEntries

func (b *BPFMap) GetMaxEntries() uint32

GetMaxEntries returns the map's capacity. Note: for ring buffer and perf buffer, maxEntries is the capacity in bytes.

func (*BPFMap) GetValue

func (b *BPFMap) GetValue(key interface{}) ([]byte, error)

func (*BPFMap) Iterator

func (b *BPFMap) Iterator() *BPFMapIterator

func (*BPFMap) KeySize

func (b *BPFMap) KeySize() int

func (*BPFMap) Pin

func (b *BPFMap) Pin(pinPath string) error

func (*BPFMap) Resize

func (b *BPFMap) Resize(maxEntries uint32) error

Resize changes the map's capacity to maxEntries. It should be called after the module was initialized but prior to it being loaded with BPFLoadObject. Note: for ring buffer and perf buffer, maxEntries is the capacity in bytes.

func (*BPFMap) SetPinPath

func (b *BPFMap) SetPinPath(pinPath string) error

func (*BPFMap) Unpin

func (b *BPFMap) Unpin(pinPath string) error

func (*BPFMap) Update

func (b *BPFMap) Update(key, value interface{}) error

func (*BPFMap) ValueSize

func (b *BPFMap) ValueSize() int

type BPFMapIterator

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

func (*BPFMapIterator) Err

func (it *BPFMapIterator) Err() error

Err returns the last error that ocurred while table.Iter or iter.Next

func (*BPFMapIterator) Key

func (it *BPFMapIterator) Key() []byte

Key returns the current key value of the iterator, if the most recent call to Next returned true. The slice is valid only until the next call to Next.

func (*BPFMapIterator) Next

func (it *BPFMapIterator) Next() bool

type BPFProg

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

func (*BPFProg) AttachKprobe

func (p *BPFProg) AttachKprobe(kp string) (*BPFLink, error)

this API should be used for kernels > 4.17

func (*BPFProg) AttachKprobeLegacy

func (p *BPFProg) AttachKprobeLegacy(kp string) (*BPFLink, error)

func (*BPFProg) AttachKretprobe

func (p *BPFProg) AttachKretprobe(kp string) (*BPFLink, error)

this API should be used for kernels > 4.17

func (*BPFProg) AttachKretprobeLegacy

func (p *BPFProg) AttachKretprobeLegacy(kp string) (*BPFLink, error)

func (*BPFProg) AttachLSM

func (p *BPFProg) AttachLSM() (*BPFLink, error)

func (*BPFProg) AttachPerfEvent

func (p *BPFProg) AttachPerfEvent(fd int) (*BPFLink, error)

func (*BPFProg) AttachRawTracepoint

func (p *BPFProg) AttachRawTracepoint(tpEvent string) (*BPFLink, error)

func (*BPFProg) AttachTracepoint

func (p *BPFProg) AttachTracepoint(tp string) (*BPFLink, error)

func (*BPFProg) AttachURetprobe

func (p *BPFProg) AttachURetprobe(pid int, path string, offset uint32) (*BPFLink, error)

AttachURetprobe attaches the BPFProgram to exit of the symbol in the library or binary at 'path' which can be relative or absolute. A pid can be provided to attach to, or -1 can be specified to attach to all processes

func (*BPFProg) AttachUprobe

func (p *BPFProg) AttachUprobe(pid int, path string, offset uint32) (*BPFLink, error)

AttachUprobe attaches the BPFProgram to entry of the symbol in the library or binary at 'path' which can be relative or absolute. A pid can be provided to attach to, or -1 can be specified to attach to all processes

func (*BPFProg) GetFd

func (p *BPFProg) GetFd() C.int

func (*BPFProg) GetType

func (p *BPFProg) GetType() uint32

func (*BPFProg) SetAutoload

func (p *BPFProg) SetAutoload(autoload bool) error

func (*BPFProg) SetTracepoint

func (p *BPFProg) SetTracepoint() error

type BPFProgType

type BPFProgType uint32

BPFProgType is an enum as defined in https://elixir.bootlin.com/linux/latest/source/include/uapi/linux/bpf.h

type LinkType

type LinkType int
const (
	Tracepoint LinkType = iota
	RawTracepoint
	Kprobe
	Kretprobe
	KprobeLegacy
	KretprobeLegacy
	LSM
	PerfEvent
	Uprobe
	Uretprobe
)

type Module

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

func NewModuleFromBuffer

func NewModuleFromBuffer(bpfObjBuff []byte, bpfObjName string) (*Module, error)

func NewModuleFromFile

func NewModuleFromFile(bpfObjFile string) (*Module, error)

func (*Module) BPFLoadObject

func (m *Module) BPFLoadObject() error

func (*Module) Close

func (m *Module) Close()

func (*Module) GetMap

func (m *Module) GetMap(mapName string) (*BPFMap, error)

func (*Module) GetProgram

func (m *Module) GetProgram(progName string) (*BPFProg, error)

func (*Module) InitPerfBuf

func (m *Module) InitPerfBuf(mapName string, eventsChan chan []byte, lostChan chan uint64, pageCnt int) (*PerfBuffer, error)

func (*Module) InitRingBuf

func (m *Module) InitRingBuf(mapName string, eventsChan chan []byte) (*RingBuffer, error)

func (*Module) TcHookInit

func (m *Module) TcHookInit() *TcHook

type PerfBuffer

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

func (*PerfBuffer) Close

func (pb *PerfBuffer) Close()

func (*PerfBuffer) Start

func (pb *PerfBuffer) Start()

func (*PerfBuffer) Stop

func (pb *PerfBuffer) Stop()

type RingBuffer

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

func (*RingBuffer) Close

func (rb *RingBuffer) Close()

func (*RingBuffer) Start

func (rb *RingBuffer) Start()

func (*RingBuffer) Stop

func (rb *RingBuffer) Stop()

type TcAttachPoint

type TcAttachPoint uint32
const (
	BPFTcIngress       TcAttachPoint = C.BPF_TC_INGRESS
	BPFTcEgress        TcAttachPoint = C.BPF_TC_EGRESS
	BPFTcIngressEgress TcAttachPoint = C.BPF_TC_INGRESS | C.BPF_TC_EGRESS
	BPFTcCustom        TcAttachPoint = C.BPF_TC_CUSTOM
)

type TcFlags

type TcFlags uint32
const (
	BpfTcFReplace TcFlags = C.BPF_TC_F_REPLACE
)

type TcHook

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

func (*TcHook) Attach

func (hook *TcHook) Attach(tcOpts *TcOpts) error

func (*TcHook) Create

func (hook *TcHook) Create() error

func (*TcHook) Destroy

func (hook *TcHook) Destroy() error

func (*TcHook) Detach

func (hook *TcHook) Detach(tcOpts *TcOpts) error

func (*TcHook) GetInterfaceIndex

func (hook *TcHook) GetInterfaceIndex() int

func (*TcHook) Query

func (hook *TcHook) Query(tcOpts *TcOpts) error

func (*TcHook) SetAttachPoint

func (hook *TcHook) SetAttachPoint(attachPoint TcAttachPoint)

func (*TcHook) SetInterfaceByIndex

func (hook *TcHook) SetInterfaceByIndex(ifaceIdx int)

func (*TcHook) SetInterfaceByName

func (hook *TcHook) SetInterfaceByName(ifaceName string) error

func (*TcHook) SetParent

func (hook *TcHook) SetParent(a int, b int)

type TcOpts

type TcOpts struct {
	ProgFd   int
	Flags    TcFlags
	ProgId   uint
	Handle   uint
	Priority uint
}

Directories

Path Synopsis

Jump to

Keyboard shortcuts

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