conntracer

README

go-conntracer-bpf

go-conntracer-bpf is a library for Go for tracing network connection (TCP) events (connect, accept) on BPF kprobe inspired by weaveworks/tcptracer-bpf. go-conntracer-bpf is implemented on top of libbpf, which is a representative C library for BPF included Linux kernel.

Features

• Low-overhead tracing by aggregating connection events in kernel.
• BPF CO-RE (Compile Once – Run Everywhere)-enabled

Prerequisites

Compilation phase

• libbpf source code
• Clang/LLVM >= 9

Runtime phase

• Linux kernel version >= 5.6 (due to batch ops to bpf maps)
• Linux kernel to be built with BTF type information. See https://github.com/libbpf/libbpf#bpf-co-re-compile-once--run-everywhere.

Common to both phase

• libelf and zlib libraries

Usage

• godoc

Projects using go-conntracer-bpf

• yuuki/shawk

Documentation

Overview

Package conntracer provides a way to capture network connection events for Linux. It uses the BPF kprobe.

Example

package main

import (
	"fmt"
	"time"

	conntracer "github.com/yuuki/go-conntracer-bpf"
)

func main() {
	// Load bpf program to kernel.
	t, err := conntracer.NewTracer()
	if err != nil {
		fmt.Println("failed to prepare tracer: ", err)
		return
	}
	defer t.Close()

	cb := func(flows []*conntracer.Flow) error {
		for _, flow := range flows {
			fmt.Printf("%v\n", flow)
		}
		return nil
	}

	// Start process of periodically polling network flows.
	t.Start(cb, 1*time.Second)

	// Stop process of polling them.
	t.Stop()
}

Index

• type Flow
• type FlowDirection
• type FlowStat
• type Tracer
  • func NewTracer() (*Tracer, error)
  • func (t *Tracer) Close()
  • func (t *Tracer) DumpFlows() ([]*Flow, error)
  • func (t *Tracer) Start(cb func([]*Flow) error, interval time.Duration)
  • func (t *Tracer) Stop()

Examples

• Package

Types

type Flow

type Flow struct {
	SAddr       *net.IP
	DAddr       *net.IP
	ProcessName string
	LPort       uint16 // Listening port
	Direction   FlowDirection
	LastPID     uint32
	Stat        *FlowStat
}

Flow is a bunch of aggregated connections group by listening port.

type FlowDirection

type FlowDirection uint8

FlowDirection are bitmask that represents both Active or Passive.

const (
	// FlowUnknown are unknown flow.
	FlowUnknown FlowDirection = 1 << iota
	// FlowActive are 'active open'.
	FlowActive
	// FlowPassive are 'passive open'
	FlowPassive
)

type FlowStat

type FlowStat struct {
	NewConnections uint32
}

FlowStat is an statistics for Flow.

type Tracer

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

Tracer is an object for state retention.

func NewTracer

func NewTracer() (*Tracer, error)

NewTracer creates a Tracer object.

func (*Tracer) Close

func (t *Tracer) Close()

Close closes tracer.

func (*Tracer) DumpFlows

func (t *Tracer) DumpFlows() ([]*Flow, error)

DumpFlows gets and deletes all flows.

func (*Tracer) Start

func (t *Tracer) Start(cb func([]*Flow) error, interval time.Duration)

Start starts polling loop.

func (*Tracer) Stop

func (t *Tracer) Stop()

Stop stops polling loop.