HoneyBadger

README

===========
HoneyBadger
===========


.. image:: http://honeybadger.readthedocs.org/en/latest/_images/honey_badger-white-sm-1.png

|

.. image:: https://drone.io/github.com/david415/HoneyBadger/status.png
  :target: https://drone.io/github.com/david415/HoneyBadger/latest

.. image:: https://coveralls.io/repos/david415/HoneyBadger/badge.svg?branch=master
  :target: https://coveralls.io/r/david415/HoneyBadger?branch=master 

.. image:: https://api.flattr.com/button/flattr-badge-large.png
  :target: https://flattr.com/submit/auto?user_id=david415&url=https%3A%2F%2Fgithub.com%2Fdavid415%2FHoneyBadger



project goals
-------------

* HoneyBadger is primarily a comprehensive TCP stream analysis tool for detecting and recording TCP attacks. Perhaps it can assist in discovering 0-days and botnets.

* HoneyBadger will include a variety of TCP stream injections attacks (it now includes 2) which prove that the TCP attack detection is reliable.


details
-------

* Read about HoneyBadger's design and implementation: https://honeybadger.readthedocs.org/

* Read the `manual integration procedure`_ - a reproduciable procedure which proves HoneyBadger's TCP injection attack detection is reliable; **in less than 2 minutes you can perform a test on your loopback interface... and test that HoneyBadger can detect injected data into a netcat client-server connection.**
.. _manual integration procedure: https://honeybadger.readthedocs.org/en/latest/#manual-integration-test-with-netcat


* Read the godoc `autogenerated API documentation`_

.. _autogenerated API documentation: https://godoc.org/github.com/david415/HoneyBadger


usage note
----------
It is not a good idea to run network traffic analysis tools as root.
In Linux you can run these tools as an unprivileged user after you run setcap as root like this::

   # setcap cap_net_raw,cap_net_admin=eip honeyBadger


=======
license
=======

HoneyBadger is free software made available via the GPL3... except for small sections of code which are BSD licensed.


=======
contact
=======

* email dstainton415@gmail.com
* gpg key ID 0x836501BE9F27A723
* gpg fingerprint F473 51BD 87AB 7FCF 6F88  80C9 8365 01BE 9F27 A723

Documentation

Index

• Constants
• func NewSniffer(options *types.SnifferDriverOptions, dispatcher PacketDispatcher) types.PacketSource
• type Connection
  • func (c *Connection) Close()
  • func (c *Connection) GetConnectionHash() types.ConnectionHash
  • func (c *Connection) GetLastSeen() time.Time
  • func (c *Connection) ReceivePacket(p *types.PacketManifest)
  • func (c *Connection) SetPacketLogger(logger types.PacketLogger)
• type ConnectionFactory
• type ConnectionInterface
• type ConnectionOptions
• type DefaultConnFactory
  • func (f *DefaultConnFactory) Build(options ConnectionOptions) ConnectionInterface
• type Dispatcher
  • func NewDispatcher(options DispatcherOptions, connectionFactory ConnectionFactory, ...) *Dispatcher
  • func (i *Dispatcher) CloseAllConnections() int
  • func (i *Dispatcher) CloseOlderThan(t time.Time) int
  • func (i *Dispatcher) Connections() []ConnectionInterface
  • func (i *Dispatcher) GetObservedConnectionsChan(count int) chan bool
  • func (i *Dispatcher) ReceivePacket(p *types.PacketManifest)
  • func (i *Dispatcher) Start()
  • func (i *Dispatcher) Stop()
• type DispatcherOptions
• type OrderedCoalesce
  • func NewOrderedCoalesce(log types.Logger, flow *types.TcpIpFlow, pageCache *pageCache, ...) *OrderedCoalesce
  • func (o *OrderedCoalesce) Close()
• type PacketDispatcher
• type Sniffer
  • func (i *Sniffer) GetStartedChan() chan bool
  • func (i *Sniffer) SetSupervisor(supervisor types.Supervisor)
  • func (i *Sniffer) Start()
  • func (i *Sniffer) Stop()
• type Supervisor
  • func NewSupervisor(options SupervisorOptions) *Supervisor
  • func (b Supervisor) GetDispatcher() PacketDispatcher
  • func (b Supervisor) GetSniffer() types.PacketSource
  • func (b Supervisor) Run()
  • func (b Supervisor) Stopped()
• type SupervisorOptions
• type TimedRawPacket

Constants

const (
	// Stop looking for handshake hijack after several
	// packets have traversed the connection after entering
	// into TCP_DATA_TRANSFER state
	FIRST_FEW_PACKETS = 12

	// TCP states
	TCP_UNKNOWN                = 0
	TCP_CONNECTION_REQUEST     = 1
	TCP_CONNECTION_ESTABLISHED = 2
	TCP_DATA_TRANSFER          = 3
	TCP_CONNECTION_CLOSING     = 4
	TCP_INVALID                = 5
	TCP_CLOSED                 = 6

	// initiating TCP closing finite state machine
	TCP_FIN_WAIT1 = 0
	TCP_FIN_WAIT2 = 1
	TCP_TIME_WAIT = 2
	TCP_CLOSING   = 3

	// initiated TCP closing finite state machine
	TCP_CLOSE_WAIT = 0
	TCP_LAST_ACK   = 1
)

Functions

func NewSniffer

func NewSniffer(options *types.SnifferDriverOptions, dispatcher PacketDispatcher) types.PacketSource

NewSniffer creates a new Sniffer struct

Types

type Connection

type Connection struct {
	ConnectionOptions

	ClientStreamRing *types.Ring
	ServerStreamRing *types.Ring
	ClientCoalesce   *OrderedCoalesce
	ServerCoalesce   *OrderedCoalesce
	PacketLogger     types.PacketLogger
	// contains filtered or unexported fields
}

Connection is used to track client and server flows for a given TCP connection. We implement a basic TCP finite state machine and track state in order to detect hanshake hijack and other TCP attacks such as segment veto and sloppy injection.

func (*Connection) Close

func (c *Connection) Close()

Close can be used by the the connection or the dispatcher to close the connection

func (*Connection) GetConnectionHash

func (c *Connection) GetConnectionHash() types.ConnectionHash

func (*Connection) GetLastSeen

func (c *Connection) GetLastSeen() time.Time

GetLastSeen returns the lastSeen timestamp after grabbing the lock

func (*Connection) ReceivePacket

func (c *Connection) ReceivePacket(p *types.PacketManifest)

ReceivePacket implements a TCP finite state machine which is loosely based off of the simplified FSM in this paper: http://ants.iis.sinica.edu.tw/3bkmj9ltewxtsrrvnoknfdxrm3zfwrr/17/p520460.pdf The goal is to detect all manner of content injection.

func (*Connection) SetPacketLogger

func (c *Connection) SetPacketLogger(logger types.PacketLogger)

type ConnectionFactory

type ConnectionFactory interface {
	Build(ConnectionOptions) ConnectionInterface
}

type ConnectionInterface

type ConnectionInterface interface {
	Close()
	SetPacketLogger(types.PacketLogger)
	GetConnectionHash() types.ConnectionHash
	GetLastSeen() time.Time
	ReceivePacket(*types.PacketManifest)
}

type ConnectionOptions

type ConnectionOptions struct {
	MaxBufferedPagesTotal         int
	MaxBufferedPagesPerConnection int
	MaxRingPackets                int
	PageCache                     *pageCache
	LogDir                        string
	LogPackets                    bool
	AttackLogger                  types.Logger
	DetectHijack                  bool
	DetectInjection               bool
	DetectCoalesceInjection       bool
	Pool                          *map[types.ConnectionHash]ConnectionInterface
}

type DefaultConnFactory

type DefaultConnFactory struct {
}

func (*DefaultConnFactory) Build

func (f *DefaultConnFactory) Build(options ConnectionOptions) ConnectionInterface

type Dispatcher

type Dispatcher struct {
	PacketLoggerFactory types.PacketLoggerFactory
	// contains filtered or unexported fields
}

Inquisitor sets up the connection pool and is an abstraction layer for dealing with incoming packets weather they be from a pcap file or directly off the wire.

func NewDispatcher

func NewDispatcher(options DispatcherOptions, connectionFactory ConnectionFactory, packetLoggerFactory types.PacketLoggerFactory) *Dispatcher

NewInquisitor creates a new Inquisitor struct

func (*Dispatcher) CloseAllConnections

func (i *Dispatcher) CloseAllConnections() int

CloseAllConnections closes all connections in the pool.

func (*Dispatcher) CloseOlderThan

func (i *Dispatcher) CloseOlderThan(t time.Time) int

CloseOlderThan takes a Time argument and closes all the connections that have not received packet since that specified time

func (*Dispatcher) Connections

func (i *Dispatcher) Connections() []ConnectionInterface

connectionsLocked returns a slice of Connection pointers.

func (*Dispatcher) GetObservedConnectionsChan

func (i *Dispatcher) GetObservedConnectionsChan(count int) chan bool

func (*Dispatcher) ReceivePacket

func (i *Dispatcher) ReceivePacket(p *types.PacketManifest)

func (*Dispatcher) Start

func (i *Dispatcher) Start()

Start... starts the TCP attack inquisition!

func (*Dispatcher) Stop

func (i *Dispatcher) Stop()

Stop... stops the TCP attack inquisition!

type DispatcherOptions

type DispatcherOptions struct {
	BufferedPerConnection    int
	BufferedTotal            int
	LogDir                   string
	LogPackets               bool
	MaxPcapLogRotations      int
	MaxPcapLogSize           int
	TcpIdleTimeout           time.Duration
	MaxRingPackets           int
	Logger                   types.Logger
	DetectHijack             bool
	DetectInjection          bool
	DetectCoalesceInjection  bool
	MaxConcurrentConnections int
}

InquisitorOptions are user set parameters for specifying the details of how to proceed with honey_bager's TCP connection monitoring. More parameters should soon be added here!

type OrderedCoalesce

type OrderedCoalesce struct {
	// MaxBufferedPagesTotal is an upper limit on the total number of pages to
	// buffer while waiting for out-of-order packets.  Once this limit is
	// reached, the assembler will degrade to flushing every connection it
	// gets a packet for.  If <= 0, this is ignored.
	MaxBufferedPagesTotal int
	// MaxBufferedPagesPerConnection is an upper limit on the number of pages
	// buffered for a single flow.  Should this limit be reached for a
	// particular flow, the smallest sequence number will be flushed, along
	// with any contiguous data.  If <= 0, this is ignored.
	MaxBufferedPagesPerFlow int

	Flow       *types.TcpIpFlow
	StreamRing *types.Ring

	PageCache *pageCache

	DetectCoalesceInjection bool
	// contains filtered or unexported fields
}

func NewOrderedCoalesce

func NewOrderedCoalesce(log types.Logger, flow *types.TcpIpFlow, pageCache *pageCache, streamRing *types.Ring, maxBufferedPagesTotal, maxBufferedPagesPerFlow int, DetectCoalesceInjection bool) *OrderedCoalesce

func (*OrderedCoalesce) Close

func (o *OrderedCoalesce) Close()

Close returns all used pages to the page cache

type PacketDispatcher

type PacketDispatcher interface {
	ReceivePacket(*types.PacketManifest)
	GetObservedConnectionsChan(int) chan bool
	Connections() []ConnectionInterface
}

type Sniffer

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

Sniffer sets up the connection pool and is an abstraction layer for dealing with incoming packets weather they be from a pcap file or directly off the wire.

func (*Sniffer) GetStartedChan

func (i *Sniffer) GetStartedChan() chan bool

func (*Sniffer) SetSupervisor

func (i *Sniffer) SetSupervisor(supervisor types.Supervisor)

func (*Sniffer) Start

func (i *Sniffer) Start()

Start... starts the TCP attack inquisition!

func (*Sniffer) Stop

func (i *Sniffer) Stop()

type Supervisor

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

func NewSupervisor

func NewSupervisor(options SupervisorOptions) *Supervisor

func (Supervisor) GetDispatcher

func (b Supervisor) GetDispatcher() PacketDispatcher

func (Supervisor) GetSniffer

func (b Supervisor) GetSniffer() types.PacketSource

func (Supervisor) Run

func (b Supervisor) Run()

func (Supervisor) Stopped

func (b Supervisor) Stopped()

type SupervisorOptions

type SupervisorOptions struct {
	SnifferDriverOptions *types.SnifferDriverOptions
	DispatcherOptions    DispatcherOptions
	SnifferFactory       func(*types.SnifferDriverOptions, PacketDispatcher) types.PacketSource
	ConnectionFactory    ConnectionFactory
	PacketLoggerFactory  types.PacketLoggerFactory
}

type TimedRawPacket

type TimedRawPacket struct {
	Timestamp time.Time
	RawPacket []byte
}