strategy

Documentation

Overview

Package strategy provides types and functions for creating Geneva strategies.

A Geneva strategy consists of zero or more action trees that can be applied to inbound or outbound packets. The actions trees encode what actions to take on a packet. A strategy, conceptually, looks like this:

outbound-forest \/ inbound-forest

"outbound-forest" and "inbound-forest" are ordered lists of "(trigger, action tree)" pairs. The Geneva paper calls these ordered lists "forests". The outbound and inbound forests are separated by the `\/` characters (that is a backslash followed by a forward-slash); if the strategy omits one or the other, then that side of the `\/` is left empty. For example, a strategy that only includes an outbound forest would take the form `outbound \/`, whereas an inbound-only strategy would be `\/ inbound`.

The original Geneva paper does not have a name for these (trigger, action tree) pairs. In practice, however, the Python code actually defines an action tree as a (trigger, action) pair, where the "action" is the root of a tree of actions. This package follows this nomenclature as well.

A real example, taken from the [original paper][geneva-paper] (pg 2202), would look like this:

[TCP:flags:S]-
   duplicate(
      tamper{TCP:flags:replace:SA}(
         send),
       send)-| \/
[TCP:flags:R]-drop-|

In this example, the outbound forest would trigger on TCP packets that have just the `SYN` flag set, and would perform a few different actions on those packets. The inbound forest would only apply to TCP packets with the `RST` flag set, and would simply drop them. Each of the forests in the example are made up of a single (trigger, action tree) pair.

Index

• type Direction
  • func (d Direction) String() string
• type Forest
• type Strategy
  • func ParseStrategy(strategy string) (*Strategy, error)
  • func (s *Strategy) Apply(packet gopacket.Packet, dir Direction) ([]gopacket.Packet, error)
  • func (s *Strategy) String() string

Examples

• ParseStrategy

Types

type Direction

type Direction int

Direction is the direction of a packet: either inbound (ingress) or outbound (egress).

const (
	// DirectionInbound indicates a packet received from a remote host (i.e., inbound or ingress
	// traffic).
	DirectionInbound Direction = iota
	// DirectionOutbound indicates a packet to be sent to a remote host (i.e., outbound or
	// egress traffic).
	DirectionOutbound
)

func (Direction) String

func (d Direction) String() string

String returns a string representation of the direction (either "inbound" or "outbound").

type Forest

type Forest []*actions.ActionTree

Forest refers to an ordered list of (trigger, action tree) pairs.

type Strategy

type Strategy struct {
	Inbound  Forest
	Outbound Forest
}

Strategy is the top-level Geneva construct that describes potential inbound and outbound changes to packets.

func ParseStrategy

func ParseStrategy(strategy string) (*Strategy, error)

ParseStrategy parses a string representation of a strategy into the actual Strategy object.

If the string is malformed, an error will be returned instead.

Example

package main

import (
	"fmt"

	"github.com/getlantern/geneva/strategy"
)

func main() {
	str := `
[TCP:flags:SA]-duplicate(send,send)-|
[TCP:flags:PA]-duplicate(duplicate(send,drop),send)-|
\/
[TCP:flags:S]-send-|`

	s, _ := strategy.ParseStrategy(str)

	fmt.Printf("%s", s)
}

Output:

[TCP:flags:SA]-duplicate-| [TCP:flags:PA]-duplicate(duplicate(,drop),)-| \/ [TCP:flags:S]-send-|

func (*Strategy) Apply

func (s *Strategy) Apply(packet gopacket.Packet, dir Direction) ([]gopacket.Packet, error)

Apply applies the strategy to a given packet.

func (*Strategy) String

func (s *Strategy) String() string

String returns a string representation of this Strategy.