This is a reimplementation of the client- and server-side rule processing mechanisms of the Geneva project.
Geneva is both a method to describe ways of manipulating packets to attempt to circumvent censorship, and a genetic
algorithm (GENetic EVAsion) that one can deploy to discover new circumventions. This package does not implement the
population manager or evaluator; the dependency-free mutate package provides the strategy mutation and crossover
primitives those systems need. More broadly, though, one can encode arbitrary instructions for packet manipulation using Geneva
rules as a sort of "standard syntax", although the use case outside of censorship circumvention may be somewhat tenuous.
This package aims to implement the same triggers and actions that the Geneva project's canonical Python package does. Please note: this package is a work-in-progress, and there are still things left to implement.
Geneva rules are called strategies. A strategy consists of zero or more action trees that can be applied to inbound or outbound packets. The actions trees define both a trigger and a tree of actions to take on a packet if the trigger matches. The result of an action tree will be zero or more packets that should replace the original packet, which then can be reinjected into the host OS' network stack.
Let's work from the top down. 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 (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.
The outbound forest for the above action in graph form looks like this:
In a forest, each action tree must adhere to the syntax [trigger]-action-|. The action is optional: canonical Geneva allows trigger-only passthrough trees such as [TCP:flags:A]-|, and parses strategies wrapped in a single pair of hanging double quotes (e.g. "\/ [TCP:flags:A]-drop-|"). The parser rejects branching actions
(duplicate and fragment) in inbound trees because inbound evaluation is single-in/single-out.
A trigger defines a way to match packets so that an action tree can be applied to them. In the example above, the first
trigger is [TCP:flags:S]. This is a trigger that matches on the TCP segment's flags field, and requires that only
the SYN flag be set. (Note that this trigger will not fire for packets that have, i.e., both SYN and ACK set.) If
the packet is not a TCP packet, or the flags do not match exactly, then this trigger will not fire. As a
compatibility note (matching canonical Geneva), earlier versions of this library treated a bare flag set such as
[TCP:flags:A] as a subset match that fired whenever at least those bits were set; matching is now exact. To opt
back into subset matching, append a *: [TCP:flags:A*] fires for any segment with ACK set.
Triggers may include a fourth, integer gas field. Positive gas bounds how many matching packets can fire the tree, zero disables it, and negative gas is a bomb that starts firing after that many matching packets. For example,
An empty trigger value is only valid where it denotes "no data": [TCP:load:] matches packets with no payload, and
data-less options such as [TCP:options-sackok:] match their option whenever present. Empty values on all other
fields are rejected when parsing or validating, since they could only ever produce a trigger that never fires.
[TCP:flags:S:2] fires twice, while [TCP:flags:S:-2] suppresses two matches and fires from the third onward.
An action simply encodes steps to manipulate a packet. There are a number of actions described in the Geneva paper:
The "send" action simply yields the given packet. (A quirk—what the paper calls canonical syntax—is to elide any "send" actions in the action tree. For instance, the action "duplicate(,)" is equivalent to "duplicate(send,send)". Bear this in mind when reading Geneva strategies!)
The "drop" action discards the given packet.
The "duplicate" action copies the original packet, then applies action a1 to the original and a2 to the copy. For
example, if a1 and a2 are both "send" actions, then the action will yield two packets identical to the first.
The "fragment" action takes the original packet and fragments it, applying a1 to one of the fragments and a2 to the
other. Since both the IP and TCP layers support fragmentation, the rule must specify which layer's payload to
fragment. The first fragment will include up to offset bytes of the layer's payload; the second fragment will contain
the rest. As an example, given an IPv4 packet with a 60-byte payload and an 8-byte offset, the first fragment will have
the same IP header as the original packet (aside from the fields that must be fixed) and then the first eight bytes of
the payload. The second fragment will contain the other 52 bytes. (You can also indicate that the fragments be returned
out-of-order; i.e., reversed, by specifying "False" for the inOrder argument.) TCP fragmentation also supports an
optional fourth overlap field, e.g., fragment{TCP:8:True:4}, which repeats that many bytes of payload in both
fragments.
The "tamper" action takes the original packet and modifies it in some fashion, depending on the protocol, field, and
mode given. There are three modes: replace, corrupt, and add. The "replace" mode will replace the value of the given
field with newValue; the "corrupt" mode will replace the value with random data; and the "add" mode adds newValue to
the field's current value, wrapping at the field's bit size. Add mode is only valid for numeric scalar fields (e.g.,
seq, ack, ttl); it is rejected for the flags bitmap, payload (load), options, and address fields. (Note that
add is one of the modes the Python code supports that are not defined in the original Geneva paper.)
The "sleep" action pauses for the given duration — expressed in (fractional) seconds, e.g., sleep{0.5} — before
applying its child action, and therefore before the resulting packets are emitted. The pause is synchronous, so in a
per-packet processing model it delays only the packet being processed. As in canonical Geneva, the child action is
optional: sleep{1} is shorthand for sleep{1}(send).
Additionally, note that not all actions are valid for both inbound and outbound directions. The Python code mentions
that "branching actions are not supported on inbound trees". Practically, this means that the duplicate and fragment
actions can only be applied to outbound packets, while the drop, tamper, and sleep actions can apply to packets of
either direction. The parser and Validate enforce this constraint.
Currently only IPv4 and TCP are supported. There are plans to add support for UDP in the future (although pull requests
are welcome! Look at TCPTamperAction and IPv4TamperAction in actions/tamper_action.go as examples.
UDPTamperAction must implement the actions.Action interface). There are no plans at the moment to add support
for IPv6.
See https://censorship.ai for more information about Geneva itself.