HoneyBadger

package module
v0.0.0-...-e421041 Latest Latest
Warning

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

Go to latest
Published: Jun 14, 2015 License: GPL-3.0 Imports: 15 Imported by: 0

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

View Source
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
)

Variables

This section is empty.

Functions

func NewSniffer

func NewSniffer(options SnifferOptions) types.PacketSource

NewSniffer creates a new Sniffer struct

Types

type BadgerSupervisor

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

func NewBadgerSupervisor

func NewBadgerSupervisor(snifferOptions SnifferOptions, dispatcherOptions DispatcherOptions, snifferFactoryFunc func(SnifferOptions) types.PacketSource, connectionFactory ConnectionFactory, packetLoggerFactory types.PacketLoggerFactory) *BadgerSupervisor

func (BadgerSupervisor) GetDispatcher

func (b BadgerSupervisor) GetDispatcher() PacketDispatcher

func (BadgerSupervisor) GetSniffer

func (b BadgerSupervisor) GetSniffer() types.PacketSource

func (BadgerSupervisor) Run

func (b BadgerSupervisor) Run()

func (BadgerSupervisor) Stopped

func (b BadgerSupervisor) Stopped()

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

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 SnifferOptions

type SnifferOptions struct {
	Interface    string
	Filename     string
	WireDuration time.Duration
	Filter       string
	Snaplen      int32
	Dispatcher   PacketDispatcher
	Supervisor   types.Supervisor
	UseAfPacket  bool
	UseBpf       bool
}

SnifferOptions are user set parameters for specifying how to receive packets.

type TimedRawPacket

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

Directories

Path Synopsis
Godeps
_workspace/src/github.com/google/gopacket
Package gopacket provides packet decoding for the Go language.
Package gopacket provides packet decoding for the Go language.
_workspace/src/github.com/google/gopacket/afpacket
Package afpacket provides Go bindings for MMap'd AF_PACKET socket reading.
Package afpacket provides Go bindings for MMap'd AF_PACKET socket reading.
_workspace/src/github.com/google/gopacket/bytediff
Package bytediff provides a simple diff utility for looking at differences in byte slices.
Package bytediff provides a simple diff utility for looking at differences in byte slices.
_workspace/src/github.com/google/gopacket/dumpcommand
Package dumpcommand implements a run function for pfdump and pcapdump with many similar flags/features to tcpdump.
Package dumpcommand implements a run function for pfdump and pcapdump with many similar flags/features to tcpdump.
_workspace/src/github.com/google/gopacket/examples/arpscan
arpscan implements ARP scanning of all interfaces' local networks using gopacket and its subpackages.
arpscan implements ARP scanning of all interfaces' local networks using gopacket and its subpackages.
_workspace/src/github.com/google/gopacket/examples/bidirectional
This binary provides an example of connecting up bidirectional streams from the unidirectional streams provided by gopacket/tcpassembly.
This binary provides an example of connecting up bidirectional streams from the unidirectional streams provided by gopacket/tcpassembly.
_workspace/src/github.com/google/gopacket/examples/bytediff
This binary shows how to display byte differences to users via the bytediff library.
This binary shows how to display byte differences to users via the bytediff library.
_workspace/src/github.com/google/gopacket/examples/httpassembly
This binary provides sample code for using the gopacket TCP assembler and TCP stream reader.
This binary provides sample code for using the gopacket TCP assembler and TCP stream reader.
_workspace/src/github.com/google/gopacket/examples/pcapdump
The pcapdump binary implements a tcpdump-like command line tool with gopacket using pcap as a backend data collection mechanism.
The pcapdump binary implements a tcpdump-like command line tool with gopacket using pcap as a backend data collection mechanism.
_workspace/src/github.com/google/gopacket/examples/pfdump
The pfdump binary implements a tcpdump-like command line tool with gopacket using pfring as a backend data collection mechanism.
The pfdump binary implements a tcpdump-like command line tool with gopacket using pfring as a backend data collection mechanism.
_workspace/src/github.com/google/gopacket/examples/statsassembly
This binary provides sample code for using the gopacket TCP assembler raw, without the help of the tcpreader library.
This binary provides sample code for using the gopacket TCP assembler raw, without the help of the tcpreader library.
_workspace/src/github.com/google/gopacket/examples/synscan
synscan implements a TCP syn scanner on top of pcap.
synscan implements a TCP syn scanner on top of pcap.
_workspace/src/github.com/google/gopacket/examples/util
Package util provides shared utilities for all gopacket examples.
Package util provides shared utilities for all gopacket examples.
_workspace/src/github.com/google/gopacket/layers
Package layers provides decoding layers for many common protocols.
Package layers provides decoding layers for many common protocols.
_workspace/src/github.com/google/gopacket/macs
Package macs provides an in-memory mapping of all valid Ethernet MAC address prefixes to their associated organization.
Package macs provides an in-memory mapping of all valid Ethernet MAC address prefixes to their associated organization.
_workspace/src/github.com/google/gopacket/pcap
Package pcap allows users of gopacket to read packets off the wire or from pcap files.
Package pcap allows users of gopacket to read packets off the wire or from pcap files.
_workspace/src/github.com/google/gopacket/pcap/gopacket_benchmark
This benchmark reads in file <tempdir>/gopacket_benchmark.pcap and measures the time it takes to decode all packets from that file.
This benchmark reads in file <tempdir>/gopacket_benchmark.pcap and measures the time it takes to decode all packets from that file.
_workspace/src/github.com/google/gopacket/pcapgo
Package pcapgo provides some native PCAP support, not requiring C libpcap to be installed.
Package pcapgo provides some native PCAP support, not requiring C libpcap to be installed.
_workspace/src/github.com/google/gopacket/pfring
Package pfring wraps the PF_RING C library for Go.
Package pfring wraps the PF_RING C library for Go.
_workspace/src/github.com/google/gopacket/routing
Package routing provides a very basic but mostly functional implementation of a routing table for IPv4/IPv6 addresses.
Package routing provides a very basic but mostly functional implementation of a routing table for IPv4/IPv6 addresses.
_workspace/src/github.com/google/gopacket/tcpassembly
Package tcpassembly provides TCP stream re-assembly.
Package tcpassembly provides TCP stream re-assembly.
_workspace/src/github.com/google/gopacket/tcpassembly/tcpreader
Package tcpreader provides an implementation for tcpassembly.Stream which presents the caller with an io.Reader for easy processing.
Package tcpreader provides an implementation for tcpassembly.Stream which presents the caller with an io.Reader for easy processing.
cmd
Honeybadger types package
Honeybadger types package

Jump to

Keyboard shortcuts

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