HoneyBadger

package module
v0.0.0-...-503e168 Latest Latest
Warning

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

 Go to latest Published: May 4, 2015 License: GPL-3.0 Imports: 13 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 NewPcapSniffer 

func NewPcapSniffer(options *PcapSnifferOptions) types.PacketSource

NewPcapSniffer creates a new PcapSniffer struct

Types

type BadgerSupervisor 

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

func NewBadgerSupervisor 

func NewBadgerSupervisor(snifferOptions *PcapSnifferOptions, inquisitorOptions *InquisitorOptions, snifferFactoryFunc func(*PcapSnifferOptions) types.PacketSource, connectionFactory *ConnectionFactory, packetLoggerFactoryFunc func(string, *types.TcpIpFlow) types.PacketLogger) *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 NewRealConnection 

func NewRealConnection(options *ConnectionOptions) *Connection

func (*Connection) AppendToClientStreamRing 

func (c *Connection) AppendToClientStreamRing(reassembly *types.Reassembly)

func (*Connection) Close 

func (c *Connection) Close()

func (*Connection) GetClientStreamRing 

func (c *Connection) GetClientStreamRing() *types.Ring

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)

func (*Connection) SetClientFlow 

func (c *Connection) SetClientFlow(flow *types.TcpIpFlow)

func (*Connection) SetPacketLogger 

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

func (*Connection) SetServerFlow 

func (c *Connection) SetServerFlow(flow *types.TcpIpFlow)

func (*Connection) SetState 

func (c *Connection) SetState(state uint8)

func (*Connection) Start 

func (c *Connection) Start()

Start is used to start the packet receiving goroutine for this connection... closeRequestChanListening shall be set to false for many of the TCP FSM unit tests.

func (*Connection) Stop 

func (c *Connection) Stop()

stop frees up all resources used by the connection

type ConnectionFactory 

type ConnectionFactory struct {
	CreateConnectionFunc func(*ConnectionOptions) ConnectionInterface
	// contains filtered or unexported fields
}

func (ConnectionFactory) Build 

func (f ConnectionFactory) Build() ConnectionInterface

type ConnectionInterface 

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

func NewConnection 

func NewConnection(options *ConnectionOptions) ConnectionInterface

NewConnection returns a new Connection struct

type ConnectionOptions 

type ConnectionOptions struct {
	MaxBufferedPagesTotal         int
	MaxBufferedPagesPerConnection int
	MaxRingPackets                int
	Pager                         *Pager
	LogDir                        string
	LogPackets                    bool
	AttackLogger                  types.Logger
	DetectHijack                  bool
	DetectInjection               bool
	DetectCoalesceInjection       bool
	Dispatcher                    PacketDispatcher
}

type Inquisitor 

type Inquisitor struct {
	InquisitorOptions

	PacketLoggerFactoryFunc func(string, *types.TcpIpFlow) types.PacketLogger
	// 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 NewInquisitor 

func NewInquisitor(options *InquisitorOptions, connectionFactory *ConnectionFactory, packetLoggerFactoryFunc func(string, *types.TcpIpFlow) types.PacketLogger) *Inquisitor

NewInquisitor creates a new Inquisitor struct

func (*Inquisitor) CloseAllConnections 

func (i *Inquisitor) CloseAllConnections() int

CloseAllConnections closes all connections in the pool.

func (*Inquisitor) CloseOlderThan 

func (i *Inquisitor) 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 (*Inquisitor) CloseRequest 

func (i *Inquisitor) CloseRequest(conn ConnectionInterface)

func (*Inquisitor) Connections 

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

connectionsLocked returns a slice of Connection pointers.

func (*Inquisitor) GetObservedConnectionsChan 

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

func (*Inquisitor) ReceivePacket 

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

func (*Inquisitor) Start 

func (i *Inquisitor) Start()

Start... starts the TCP attack inquisition!

func (*Inquisitor) Stop 

func (i *Inquisitor) Stop()

Stop... stops the TCP attack inquisition!

type InquisitorOptions 

type InquisitorOptions struct {
	BufferedPerConnection    int
	BufferedTotal            int
	LogDir                   string
	LogPackets               bool
	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

	ConnectionClose func()

	Flow       *types.TcpIpFlow
	StreamRing *types.Ring

	DetectCoalesceInjection bool
	// contains filtered or unexported fields
}

func NewOrderedCoalesce 

func NewOrderedCoalesce(ConnectionClose func(), log types.Logger, flow *types.TcpIpFlow, pager *Pager, 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 via the Pager

type PacketDispatcher 

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

type PageReplaceRequest 

type PageReplaceRequest struct {
	Page      *page
	DoneChan  chan bool
	Inclusive bool
}

type PageRequest 

type PageRequest struct {
	Timestamp    time.Time
	ResponseChan chan *page
}

PageRequest is used to request a page from the Pager The new page will be sent on the ResponseChan and have it's timestamp set to Timestamp.

type Pager 

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

Pager is used to synchronize access to our pagecache among many goroutines. No locks are used here. Instead, we use channels to send page points between goroutines.

func NewPager 

func NewPager() *Pager

NewPager creates a new Pager struct with an initialized pagecache and channels with which to access it.

func (*Pager) Next 

func (p *Pager) Next(timestamp time.Time) *page

Next takes a timestamp argument and constructs a PageRequest, sends it to pager's requestPageChan, waits to receive a page pointer on the response channel and then returns it.

func (*Pager) Replace 

func (p *Pager) Replace(pagePtr *page)

Replace takes a page pointer argument and appends it to the pagecache's free list

func (*Pager) ReplaceAllFrom 

func (p *Pager) ReplaceAllFrom(pagePtr *page)

ReplaceAllFrom shall perform the Replace operation for all subsequently linked pages

func (*Pager) Start 

func (p *Pager) Start()

Start causes our Pager to start it's own goroutine to process pagecache requests over channels.

func (*Pager) Stop 

func (p *Pager) Stop()

Stop simply stops our Pager goroutine. It does not free up used pages.

func (*Pager) Used 

func (p *Pager) Used() int

type PcapSniffer 

type PcapSniffer struct {
	PcapSnifferOptions
	// contains filtered or unexported fields
}

PcapSniffer 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 (*PcapSniffer) GetStartedChan 

func (i *PcapSniffer) GetStartedChan() chan bool

func (*PcapSniffer) SetSupervisor 

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

func (*PcapSniffer) Start 

func (i *PcapSniffer) Start()

Start... starts the TCP attack inquisition!

func (*PcapSniffer) Stop 

func (i *PcapSniffer) Stop()

type PcapSnifferOptions 

type PcapSnifferOptions struct {
	Interface    string
	Filename     string
	WireDuration time.Duration
	Filter       string
	Snaplen      int
	Dispatcher   PacketDispatcher
	Supervisor   types.Supervisor
}
type TimedRawPacket struct {
	Timestamp time.Time
	RawPacket []byte
}

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

type TimedRawPacket 

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

Source Files

View all Source files

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
handshakeHijacker
honeyBadger
sprayInjector
Honeybadger types package
 Honeybadger types package

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.