HoneyBadger

package module
v0.0.0-...-5f1c48d Latest Latest
Warning

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

 Go to latest Published: Aug 26, 2016 License: GPL-3.0 Imports: 14 Imported by: 0

README 

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


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

|

.. image:: https://travis-ci.org/david415/HoneyBadger.svg?branch=master
  :target: https://travis-ci.org/david415/HoneyBadger

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

.. image:: https://godoc.org/github.com/david415/HoneyBadger?status.svg
  :target: https://godoc.org/github.com/david415/HoneyBadger


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

* HoneyBadger is primarily a comprehensive TCP stream analysis tool for detecting and recording TCP injection attacks.

* This git repository also includes a variety of *prototype* TCP stream injections attacks.


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


* HoneyBadger currently support 3 Data AcQuisition packet sources: libpcap, AF_PACKET and BSD_BPF.
This means that for instance on OpenBSD, you must use the BSD_BPF DAQ by specifying this CLI option::

  "-daq=BSD_BPF"


HoneyBadger attack detecton CLI examples!
-----------------------------------------

Build honeyBadger CLI command from source::

  user@go-dev2:~/gopath/src/github.com/david415/HoneyBadger/cmd/honeyBadger$ go build

Run honeyBadger against a pcap file called tshark2.pcap::

  user@go-dev2:~/gopath/src/github.com/david415/HoneyBadger/cmd/honeyBadger$ ./honeyBadger \
  -max_concurrent_connections=1000 -max_pcap_log_size=100 -max_pcap_rotations=10 -max_ring_packets=40 \
  -metadata_attack_log=false -total_max_buffer=1000 -connection_max_buffer=100 -archive_dir=./archive \
  -log_packets -l=./incoming -pcapfile=./tshark2.pcap


honeyBadger will spew lots of things to stdout. Using the above command,
it will record an attack report JSON file(s) to the "./archive" directory.
Here's an example output with a pcap file containing an ordered coalesce injection::

  2016/02/05 23:30:01 Starting libpcap packet capture on file ./tshark2.pcap
  2016/02/05 23:30:01 connected 127.0.0.1:59670-127.0.0.1:9666
  2016/02/05 23:30:01 race winner stream segment:
  2016/02/05 23:30:01 00000000  20 69 73 20 6e 65 63 65  73 73 61 72 79 20 66 6f  | is necessary fo|
  00000010  72 20 61 6e 20 6f 70 65  6e 20 73 6f 63 69 65 74  |r an open societ|
  00000020  79 20 69 6e 20 74 68 65  20 65 6c 65 63 74 72 6f  |y in the electro|
  00000030  6e 69 63 20 61 67 65 2e  20 50 72 69 76 61 63 79  |nic age. Privacy|
  00000040  20 69 73 20 6e 6f 74 20  73 65 63 72 65 63 79 2e  | is not secrecy.|
  00000050  20 41 20 70 72 69 76 61  74 65 20 6d 61 74 74 65  | A private matte|
  00000060  72 20 69 73 20 73 6f 6d  65 74 68 69 6e 67 20 6f  |r is something o|
  00000070  6e 65 20 64 6f 65 73 6e  27 74 20 77 61 6e 74 20  |ne doesn't want |
  00000080  74 68 65 20 77 68 6f 6c  65 20 77 6f 72 6c 64 20  |the whole world |
  00000090  74 6f 20 6b 6e 6f 77 2c  20 62 75 74 20 61 20 73  |to know, but a s|
  000000a0  65 63 72 65 74 20 6d 61  74 74 65 72 20 69 73 20  |ecret matter is |
  000000b0  73 6f 6d 65 74 68 69 6e  67 20 6f 6e 65 20 64 6f  |something one do|
  000000c0  65 73 6e 27 74 20 77 61  6e 74 20 61 6e 79 62 6f  |esn't want anybo|
  000000d0  64 79 20 74 6f 20 6b 6e  6f 77 2e 20 50 72 69 76  |dy to know. Priv|
  000000e0  61 63 79 20 69 73 20 74  68 65 20 70 6f 77 65 72  |acy is the power|
  000000f0  20 74 6f 20 73 65 6c 65  63 74 69 76 65 6c 79 20  | to selectively |
  00000100  72 65 76 65 61 6c 20 6f  6e 65 73 65 6c 66 20 74  |reveal oneself t|
  00000110  6f 20 74 68 65 20 77 6f  72 6c 64 2e              |o the world.|
  2016/02/05 23:30:01 race loser stream segment:
  2016/02/05 23:30:01 00000000  50 72 69 76 61 63 79 20  69 73 20 6e 65 63 65 73  |Privacy is neces|
  00000010  73 61 72 79 20 66 6f 72  20 61 6e 20 6f 70 65 6e  |sary for an open|
  00000020  20 73 6f 63 69 65 74 79  20 69 6e 20 74 68 65 20  | society in the |
  00000030  65 6c 65 63 74 72 6f 6e  69 63 20 61 67 65 2e 20  |electronic age. |
  00000040  50 72 69 76 61 63 79 20  69 73 20 6e 6f 74 20 73  |Privacy is not s|
  00000050  65 63 72 65 63 79 2e 20  41 20 70 72 69 76 61 74  |ecrecy. A privat|
  00000060  65 20 6d 61 74 74 65 72  20 69 73 20 73 6f 6d 65  |e matter is some|
  00000070  74 68 69 6e 67 20 6f 6e  65 20 64 6f 65 73 6e 27  |thing one doesn'|
  00000080  74 20 77 61 6e 74 20 74  68 65 20 77 68 6f 6c 65  |t want the whole|
  00000090  20 77 6f 72 6c 64 20 74  6f 20 6b 6e 6f 77 2c 20  | world to know, |
  000000a0  62 75 74 20 61 20 73 65  63 72 65 74 20 6d 61 74  |but a secret mat|
  000000b0  74 65 72 20 69 73 20 73  6f 6d 65 74 68 69 6e 67  |ter is something|
  000000c0  20 6f 6e 65 20 64 6f 65  73 6e 27 74 20 77 61 6e  | one doesn't wan|
  000000d0  74 20 61 6e 79 62 6f 64  79 20 74 6f 20 6b 6e 6f  |t anybody to kno|
  000000e0  77 2e 20 50 72 69 76 61  63 79 20 69 73 20 74 68  |w. Privacy is th|
  000000f0  65 20 70 6f 77 65 72 20  74 6f 20 73 65 6c 65 63  |e power to selec|
  00000100  74 69 76 65 6c 79 20 72  65 76 65 61 6c 20 6f 6e  |tively reveal on|
  00000110  65 73 65 6c 66 20 74 6f  20 74 68 65              |eself to the|
  2016/02/05 23:30:01 detected an ordered coalesce injection
  2016/02/05 23:30:01 FIN-WAIT-1: non-ACK packet received.
  2016/02/05 23:30:01 ReadPacketData got EOF
  2016/02/05 23:30:01 Close()
  2016/02/05 23:30:01 1 connection(s) closed.
  2016/02/05 23:30:01 Supervisor.Stopped()
  2016/02/05 23:30:01 graceful shutdown: packet-source stopped



Or instead you can tell honeyBadger to analyze the wire with Linux's AF_PACKET capture mode. You
should first disable offloading::

  sudo apt-get install ethtool
  sudo ethtool -K eth0 gso off
  sudo ethtool -K eth0 tso off
  sudo ethtool -K eth0 gro off


And then run honeyBadger like this::

  ./honeyBadger -max_concurrent_connections=1000 -max_pcap_log_size=100 -max_pcap_rotations=10 \
  -max_ring_packets=40 -metadata_attack_log=false -total_max_buffer=1000 -connection_max_buffer=100 \
  -archive_dir=/home/user/gopath/src/github.com/david415/HoneyBadger/cmd/honeyBadger/archive -log_packets \
  -l=/home/user/gopath/src/github.com/david415/HoneyBadger/cmd/honeyBadger/incoming -log_packets=true \
  -i=eth0 -daq=AF_PACKET

  2016/02/07 14:16:32 HoneyBadger: comprehensive TCP injection attack detection.
  2016/02/07 14:16:32 PageCache: created 1024 new pages
  2016/02/07 14:16:32 Starting AF_PACKET packet capture on interface eth0


Linux security note
-------------------
If running on Linux you can avoid running as root by using the setcap command.
In Linux you can run packet capture tools as an unprivileged user after you run setcap as root like this::

   # setcap cap_net_raw,cap_net_admin=eip honeyBadger


BSD security note
-----------------
When using the ``BSD_BPF`` sniffer, avoid running as root by making sure your user has
read-write access to ``/dev/bpf*`` If you are in the ``wheel`` group and the bpf devices
are group owned by ``wheel`` then this should work::

   # chmod g+rw /dev/bpf*


=======
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 *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) GetClientFlow 

func (c *Connection) GetClientFlow() *types.TcpIpFlow

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()
	GetClientFlow() *types.TcpIpFlow
	SetPacketLogger(types.PacketLogger)
	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
}

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(logger types.Logger, flow *types.TcpIpFlow, pageCache *pageCache, streamRing *types.Ring, maxBufferedPagesTotal, maxBufferedPagesPerFlow int, DetectCoalesceInjection bool, attackDetected *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
	Stop()
}

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) Close 

func (i *Sniffer) Close()

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
}

Source Files

View all Source files

Directories

Path Synopsis
modified to use our Sequence type instead of int64 Package blocks contains logic to detect overlap between segments of a contiguous data stream.
 modified to use our Sequence type instead of int64 Package blocks contains logic to detect overlap between segments of a contiguous data stream.
cmd
handshakeHijacker
honeyBadger
honeybadgerReportTool
honeybadgerReportToolColor
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.