zerotrace

README

ZeroTrace

Imagine you run a Web service and want to determine the network-layer round trip time to clients that connect to your Web service. An ICMP ping is unlikely to work as most home routers don't respond to ICMP echo requests. A TCP ping is also unlikely to work because home routers typically don't respond to unexpected segments with a TCP RST segment. It is generally difficult to get home routers to respond to unsolicited traffic.

The key insight of the 0trace technique is to piggyback onto an already-established TCP connection to conduct a traceroute measurement. As long as the client has an open TCP connection to our Web service, we can inject segments with increasing TTL into the TCP connection. Firewalls along the path are more likely to respond to packets with an exceeded TTL if they are part of an established TCP connection. While this technique may not always make it all the way to the client, it tends to get close.

This Go package implements the 0trace traceroute technique. The API is straightforward: Instantiate a new ZeroTrace object by calling NewZeroTrace. Then, start the object by invoking its Start method. Afterwards, you can invoke the CalcRTT method by providing the net.Conn object of an already-established TCP connection. CalcRTT returns the round trip time to the client (or the hop that's closest) as time.Duration, or an error.

Configuration

ZeroTrace's constructor expects a configuration object as argument. Take a look at the Config struct to learn more about configuration options. The function NewDefaultConfig returns a default configuration object with reasonable defaults.

Example

Use the code in the example directory to get started.

Development

To test and lint the code, run:

make

Documentation

Index

• type Config
  • func NewDefaultConfig() *Config
• type ZeroTrace
  • func NewZeroTrace(c *Config) *ZeroTrace
  • func (z *ZeroTrace) CalcRTT(conn net.Conn) (time.Duration, error)
  • func (z *ZeroTrace) Close()
  • func (z *ZeroTrace) Start() error

Types

type Config

type Config struct {
	// NumProbes determines the number of probes we're sending for a given TTL.
	NumProbes int
	// TTLStart determines the TTL at which we start sending trace packets.
	TTLStart int
	// TTLEnd determines the TTL at which we stop sending trace packets.
	TTLEnd int
	// SnapLen determines the number of bytes per frame that we want libpcap to
	// capture.  500 bytes is enough for ICMP TTL exceeded packets.
	SnapLen int32
	// PktBufTimeout determines the time we're willing to wait for packets to
	// accumulate in our receive buffer.
	PktBufTimeout time.Duration
	// Interface determines the network interface that we're going to use to
	// listen for incoming network packets.
	Interface string
}

Config holds configuration options for the ZeroTrace object.

func NewDefaultConfig

func NewDefaultConfig() *Config

NewDefaultConfig returns a configuration object containing the following defaults. *Note* that you probably need to change the networking interface.

NumProbes:     3
TTLStart:      5
TTLEnd:        32
SnapLen:       500
PktBufTimeout: time.Millisecond * 10
Interface:     "eth0"

type ZeroTrace

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

ZeroTrace implements the 0trace traceroute technique: https://seclists.org/fulldisclosure/2007/Jan/145

func NewZeroTrace

func NewZeroTrace(c *Config) *ZeroTrace

NewZeroTrace returns a new ZeroTrace object that uses the given configuration.

func (*ZeroTrace) CalcRTT

func (z *ZeroTrace) CalcRTT(conn net.Conn) (time.Duration, error)

CalcRTT starts a new 0trace traceroute and returns the RTT to the target or, if the target won't respond to us, the RTT of the hop that's closest. The given net.Conn represents an already-established TCP connection to the target. Note that the TCP connection may be corrupted as part of the 0trace measurement.

func (*ZeroTrace) Close

func (z *ZeroTrace) Close()

Close closes the ZeroTrace object.

func (*ZeroTrace) Start

func (z *ZeroTrace) Start() error

Start starts the ZeroTrace object. This function instructs ZeroTrace to start its event loop and to begin capturing network packets.