freki

README

freki

The ravenous and greedy one.

Freki is a tool for manipulating packets in userspace. Using iptable's raw table, packets are routed down into userspace where freki takes over. A set of rules is applied allowing for a large amount of flexibility. For example, you can forward all TCP ports to an HTTP honeypot and log the requests. Or you can proxy TCP port 22 into a docker container running an ssh honeypot.

There are currently two builtin loggers:

log_tcp: reads up to 1024 bytes from the connection, and then closes it.

log_http: sends a 200 OK back on every request.

Additionally, there are three mangling behaviors:

rewrite: Rewrites the incoming packet's destination port

proxy: Creates a TCP proxy for the connection to the specified target (can be an IP address, host name, or docker container)

user_conn: When using freki as a library, invoke a user-specified callback with a net.Conn

$ ./bin/freki --help
Usage:
    freki [options] [-v ...] -i=<interface> -r=<rules>
    freki -h | --help | --version
Options:
    -i --interface=<iface>  Bind to this interface.
    -r --rules=<rules>      Rules file.
    -h --help               Show this screen.
    --version               Show version.
    -v                      Enable verbose logging (-vv for very verbose)

Build

requires: go 1.7+, libnetfilter-queue-dev, libpcap-dev, iptables-dev

Rules Specification

Rules are applied in order (top down) and stop after a match is found. The match field (required) is written using BPF filter syntax. Note: not all filters may apply. For example, the ethernet src and dst headers are generally zero'd out.

rules:
  # allow packets from your machine (1.2.3.4) to reach your ssh server
  - match: tcp dst port 22 and src host 1.2.3.4
    type: passthrough
  # send all tcp coming in on 10022 to 22
  - match: tcp dst port 10022
    type: rewrite
    target: 22
  # proxy all packets coming in on 6379 on to a container named 'redis' (must exist at the time freki starts)
  - match: tcp dst port 6379
    type: proxy
    target: docker://redis:6379
  # proxy all packets coming in on 666 out to portquiz.net:666
  - match: tcp dst port 666
    type: proxy
    target: tcp://portquiz.net:666
  # log http requests on 80 and 8080
  - match: tcp port 80 or tcp port 8080
    type: log_http
  # pass connections on 7000 through 8000 to a registered handler called 'echo'
  - match: tcp portrange 7000-8000
    type: conn_handler
    target: echo
  # drop (no FIN, nothing!)
  - match: tcp portrange 5000-5010
    type: drop
  # forward all remaining tcp packets to a tcp logger. grabs 1024 bytes and then closes.
  - match: tcp
    type: log_tcp
  - match:
    type: passthrough

Notes

If freki hangs or panics, it may leave two iptables rules in place.

The simple fix is: sudo iptables -t raw -F.

Contributors

• Jonathan Camp
• glasos

License

freki is distributed under the terms of the MIT License.

Documentation

Index

• func NewConnKeyByEndpoints(clientAddr gopacket.Endpoint, clientPort gopacket.Endpoint) ckey
• func NewConnKeyByString(host, port string) ckey
• func NewConnKeyFromNetConn(conn net.Conn) ckey
• type Config
• type ConnHandlerFunc
• type HTTPLogger
  • func NewHTTPLogger(port uint) *HTTPLogger
  • func (h *HTTPLogger) Port() uint
  • func (h *HTTPLogger) Shutdown() error
  • func (h *HTTPLogger) Start(p *Processor) error
  • func (h *HTTPLogger) Type() string
• type Logger
• type Metadata
• type Processor
  • func New(ifaceName string, rules []*Rule, logger Logger) (*Processor, error)
  • func (p *Processor) AddServer(s Server)
  • func (p *Processor) Init() (err error)
  • func (p *Processor) PacketsProcessed() uint64
  • func (p *Processor) RegisterConnHandler(target string, handler ConnHandlerFunc) error
  • func (p *Processor) Shutdown() (err error)
  • func (p *Processor) Start() (err error)
• type Rule
  • func ParseRuleSpec(spec []byte) ([]*Rule, error)
  • func ReadRulesFromFile(file *os.File) ([]*Rule, error)
  • func (r *Rule) String() string
• type RuleType
• type Server
• type TCPLogger
  • func NewTCPLogger(port uint, readSize uint) *TCPLogger
  • func (h *TCPLogger) Port() uint
  • func (h *TCPLogger) Shutdown() error
  • func (h *TCPLogger) Start(p *Processor) error
  • func (h *TCPLogger) Type() string
• type TCPProxy
  • func NewTCPProxy(port uint) *TCPProxy
  • func (p *TCPProxy) Port() uint
  • func (p *TCPProxy) Shutdown() error
  • func (p *TCPProxy) Start(processor *Processor) error
  • func (p *TCPProxy) Type() string
• type UserConnServer
  • func NewUserConnServer(port uint) *UserConnServer
  • func (h *UserConnServer) Port() uint
  • func (h *UserConnServer) Shutdown() error
  • func (h *UserConnServer) Start(processor *Processor) error
  • func (h *UserConnServer) Type() string

Functions

func NewConnKeyByEndpoints

func NewConnKeyByEndpoints(clientAddr gopacket.Endpoint, clientPort gopacket.Endpoint) ckey

func NewConnKeyByString

func NewConnKeyByString(host, port string) ckey

func NewConnKeyFromNetConn

func NewConnKeyFromNetConn(conn net.Conn) ckey

Types

type Config

type Config struct {
	Version int     `yaml:"version"`
	Rules   []*Rule `yaml:"rules"`
}

type ConnHandlerFunc

type ConnHandlerFunc func(conn net.Conn, md *Metadata) error

type HTTPLogger

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

func NewHTTPLogger

func NewHTTPLogger(port uint) *HTTPLogger

func (*HTTPLogger) Port

func (h *HTTPLogger) Port() uint

func (*HTTPLogger) Shutdown

func (h *HTTPLogger) Shutdown() error

func (*HTTPLogger) Start

func (h *HTTPLogger) Start(p *Processor) error

func (*HTTPLogger) Type

func (h *HTTPLogger) Type() string

type Logger

type Logger interface {
	Debug(args ...interface{})
	Debugf(format string, args ...interface{})
	Error(args ...interface{})
	Errorf(format string, args ...interface{})
	Fatal(args ...interface{})
	Fatalf(format string, args ...interface{})
	Info(args ...interface{})
	Infof(format string, args ...interface{})
	Panic(args ...interface{})
	Panicf(format string, args ...interface{})
	Warn(args ...interface{})
	Warnf(format string, args ...interface{})
}

type Metadata

type Metadata struct {
	Added      time.Time
	Rule       *Rule
	TargetPort layers.TCPPort
}

type Processor

type Processor struct {
	Connections *connTable
	// contains filtered or unexported fields
}

func New

func New(ifaceName string, rules []*Rule, logger Logger) (*Processor, error)

func (*Processor) AddServer

func (p *Processor) AddServer(s Server)

func (*Processor) Init

func (p *Processor) Init() (err error)

func (*Processor) PacketsProcessed

func (p *Processor) PacketsProcessed() uint64

func (*Processor) RegisterConnHandler

func (p *Processor) RegisterConnHandler(target string, handler ConnHandlerFunc) error

func (*Processor) Shutdown

func (p *Processor) Shutdown() (err error)

func (*Processor) Start

func (p *Processor) Start() (err error)

type Rule

type Rule struct {
	Match  string `yaml:"match"`
	Type   string `yaml:"type"`
	Target string `yaml:"target,omitempty"`
	Name   string `yaml:"name,omitempty"`
	// contains filtered or unexported fields
}

func ParseRuleSpec

func ParseRuleSpec(spec []byte) ([]*Rule, error)

func ReadRulesFromFile

func ReadRulesFromFile(file *os.File) ([]*Rule, error)

func (*Rule) String

func (r *Rule) String() string

type RuleType

type RuleType int

const (
	Rewrite RuleType = iota
	ProxyTCP
	LogTCP
	LogHTTP
	UserConnHandler
	Drop
	PassThrough
)

type Server

type Server interface {
	Type() string
	Start(p *Processor) error
	Shutdown() error
	Port() uint
}

type TCPLogger

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

func NewTCPLogger

func NewTCPLogger(port uint, readSize uint) *TCPLogger

func (*TCPLogger) Port

func (h *TCPLogger) Port() uint

func (*TCPLogger) Shutdown

func (h *TCPLogger) Shutdown() error

func (*TCPLogger) Start

func (h *TCPLogger) Start(p *Processor) error

func (*TCPLogger) Type

func (h *TCPLogger) Type() string

type TCPProxy

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

func NewTCPProxy

func NewTCPProxy(port uint) *TCPProxy

func (*TCPProxy) Port

func (p *TCPProxy) Port() uint

func (*TCPProxy) Shutdown

func (p *TCPProxy) Shutdown() error

func (*TCPProxy) Start

func (p *TCPProxy) Start(processor *Processor) error

func (*TCPProxy) Type

func (p *TCPProxy) Type() string

type UserConnServer

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

func NewUserConnServer

func NewUserConnServer(port uint) *UserConnServer

func (*UserConnServer) Port

func (h *UserConnServer) Port() uint

func (*UserConnServer) Shutdown

func (h *UserConnServer) Shutdown() error

func (*UserConnServer) Start

func (h *UserConnServer) Start(processor *Processor) error

func (*UserConnServer) Type

func (h *UserConnServer) Type() string