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 ¶
Examples ¶
Constants ¶
const ( // MaxTreesPerForest bounds the work performed for each packet direction. MaxTreesPerForest = 64 // MaxActions bounds the total number of action nodes in a strategy. MaxActions = 256 // MaxActionDepth bounds recursive action evaluation. MaxActionDepth = 64 )
Variables ¶
var ErrInvalidStrategy = errors.New("invalid strategy")
ErrInvalidStrategy is returned when strategy DNA is structurally invalid or uses behavior outside the supported IPv4/TCP engine.
Functions ¶
Types ¶
type Direction ¶
type Direction int
Direction is the direction of a packet: either inbound (ingress) or outbound (egress).
type Forest ¶
type Forest []*actions.ActionTree
Forest refers to an ordered list of (trigger, action tree) pairs.
type Strategy ¶
Strategy is the top-level Geneva construct that describes potential inbound and outbound changes to packets.
func ParseStrategy ¶
ParseStrategy parses a string representation of a strategy into the actual Strategy object.
This matches canonical Geneva parsing: a single pair of surrounding double quotes is stripped, whitespace is tolerated between trees and around the "\/" delimiter, and an empty or quote-delimiter-only string parses into a valid, empty Strategy. An action tree may omit its action entirely (e.g. "[TCP:flags:A]-|"), in which case matching packets pass through unharmed.
If the string is malformed beyond that, 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-|
Source Files