DOCSEARCHbyAlgolia
Submit Docs

Geneva Documentation

repository·master·Indexed 24 days ago

https://github.com/kkevsterrr/geneva

An AI-driven research tool that uses genetic algorithms to evolve packet-level modification strategies to evade network censorship. It employs a Strategy DNA syntax to define action trees (duplicate, drop, tamper, fragment) that confuse censoring middleboxes without disrupting client-server communication. Supports custom packet-level actions and application plugins for fitness evaluation on Debian and CentOS systems.

Tokens
17.4K
Snippets
25
Records
88
Agent score
79%

What's inside Geneva

  1. What is Geneva and how does it work?

    master

    Geneva is an artificial intelligence tool designed to evade in-network censorship by exploiting bugs in censoring regimes (e.g., China, India, Kazakhstan). Unlike VPNs or Tor, Geneva operates on only one side of a connection (either client or server) and manipulates the network stream to confuse censors without disrupting the underlying communication. It is effective against most in-network censorship but cannot bypass IP-blocking.

    Geneva consists of two primary components:

    1. Genetic Algorithm: Used to evolve new censorship evasion strategies.
    2. Strategy Engine: Used to execute individual strategies over a network connection.

  2. How strategy evaluation works in Geneva

    master

    Strategy evaluation is the process of determining which censorship evasion strategies are most effective to guide the genetic algorithm. This is handled by evaluator.py, which assigns a numerical fitness score to each strategy based on a fitness function.

    Key concepts:

    • Fitness Score: The absolute value is less important than the relative comparison. A 'better' strategy must have a higher score than a 'worse' one.
    • Application Agnosticism: Geneva operates at the network (TCP/IP) layer. It can capture and modify traffic regardless of whether the source is curl, Google Chrome, or any other application.
    • Environment IDs: During evaluation, each strategy is assigned a random 'environment id' used for tracking. Logs are written to files named after these IDs.

  3. Use plugins to define fitness functions and test applications

    master

    Geneva uses a plugin system (located in plugins/) to drive specific applications to make forbidden requests and to define the fitness function for those applications. Plugins provide a common interface for the evaluator to launch them and retrieve fitness scores.

    To use a specific plugin during evaluation or evolution, you must specify it using the --test-type <plugin> flag. For example, to use the HTTP plugin, use --test-type http.

    Plugin Structure:

    • Client: Attempts to make a forbidden connection through the censor to an external server (or a plugin-provided server).
    • Server (Optional): Can be defined by the plugin to facilitate testing.

  4. How censorship evasion strategies work in Geneva

    master

    A censorship evasion strategy in Geneva is a description of how network traffic should be modified, rather than executable code. The strategy tells the engine how to manipulate packets to bypass censorship while maintaining client/server communication.

    Strategies are composed of packet-level building blocks:

    • duplicate: Returns two copies of the input packet.
    • drop: Returns no packets (drops the packet).
    • tamper: Returns a modified version of the input packet.
    • fragment: Returns two fragments or two segments.

    Because duplicate and fragment introduce branching, they are organized into a binary-tree structure called an action tree. Each tree is associated with a trigger that defines which packets cause the tree to execute. A collection of action trees is called a forest.

    Geneva manages two distinct forests:

    1. Outbound forest: For packets leaving the network.
    2. Inbound forest: For packets entering the network.

    Note: Due to limitations in Scapy and NFQueue, branching actions (fragment, duplicate) are disabled for inbound action forests.

  5. Understand the Geneva trial directory structure

    master

    When running evolve.py, Geneva creates a new directory under trials/ named after the current timestamp. This directory contains several subfolders used to organize data generated during the strategy evolution process:

    • data: Miscellaneous data related to strategy evaluation.
    • flags: Status files used to set events.
    • generations: Stores full generations and the 'hall of fame' after each generation.
    • logs: Stores all log files for the evaluation process.
    • packets: Stores packet captures collected during strategy evolution.

  6. Understand the Strategy Taxonomy

    master

    In Geneva, a Strategy is not code; it is a description that tells the strategy engine how to modify network traffic to evade censorship without impacting client/server communication.

    Geneva uses a three-tier taxonomy to classify these strategies:

    1. Species: The overarching bug or weakness in a censor implementation that the strategy exploits (e.g., TCB Teardown).
    2. Subspecies: The specific mechanism used to exploit that bug (e.g., injecting a TCP RST packet vs. a TCP FIN packet).
    3. Variant: Salient wireline differences within the same mechanism (e.g., corrupting the checksum field vs. corrupting the ack field on a RST packet).

    Strategies that are no longer effective (success rate < 5%) are referred to as extinct.

  7. Understand the fitness function hierarchy

    master

    Because censors typically provide only a binary signal (censored or not), Geneva uses fitness functions to encourage the genetic algorithm to search for strategies that keep TCP connections alive. The fitness function defines a hierarchy of strategies from best to worst.

    Geneva's comparison order (from highest fitness to lowest) is:

    1. Strategy that does not get censored and generates a minimal number of packets, no unused triggers, and minimal size.
    2. Strategy that does not get censored, but has unused actions, is too large, or imparts overhead.
    3. Strategy that gets censored.
    4. Strategy that does not trigger on any packets but gets censored.
    5. Strategy that breaks the underlying TCP connection.
    6. Empty strategy.

    This hierarchy enables search space reduction by quickly eliminating strategies that break the underlying connection, allowing the algorithm to focus on strategies that successfully maintain connectivity while evading detection.

  8. Strategy DNA Syntax for defining evasion strategies

    master

    Geneva uses a specific string syntax called Strategy DNA to express complex evasion strategies.

    Structure

    • Forest Separation: A strategy is divided into outbound and inbound forests using the \/ separator: <outbound forest> \/ <inbound forest>. If \/ is absent, all trees belong to the outbound forest.
    • Action Trees: Each tree starts with a trigger and ends with the terminator -|.

    Triggers

    Triggers follow the format [<protocol>:<field>:<value>] or [<protocol>:<field>:<value>:<gas>].

    • Example: [TCP:flags:S] triggers on TCP packets with the SYN flag set.
    • Gas: An optional 4th parameter specifying how many times a trigger can fire.
      • [IP:version:4:4]: Fires only on the first 4 matching IPv4 packets.
      • Bomb Trigger: If gas is negative, the trigger only fires after seeing the specified number of matching packets. e.g., [IP:version:4:-2] triggers only after 2 matching packets have been observed (it does not trigger on the first two).

    Actions and Nesting

    Actions can have up to two children (for branching actions like duplicate) or one child (for tamper).

    • Parameters: Specified within curly braces {}. e.g., tamper{TCP:flags:replace:A}.
    • Branching Syntax: [trigger]-action(left_child,right_child)-|.
    • Single Child Syntax: [trigger]-action{params}(child,)-|.
    • Leaf/No Branching: If (,) is not specified, packets emerging from the action are sent directly to the wire.

    Example

    To trigger on TCP packets with the ACK flag, duplicate them, replace the flags with R, and then corrupt the checksum: [TCP:flags:A]-duplicate(tamper{TCP:flags:replace:R}(tamper{TCP:chksum:corrupt},),)-|

    [TCP:flags:A]-duplicate(tamper{TCP:flags:replace:R}(tamper{TCP:chksum:corrupt},),)-| \/

  9. How censorship evasion strategies work

    master

    A Geneva strategy is a description (not code) of how network traffic should be modified. It uses an action tree structure to manipulate packets at the packet level.

    Core Building Blocks

    1. duplicate: Takes one packet and returns two copies.
    2. drop: Takes one packet and returns no packets.
    3. tamper: Takes one packet and returns a modified packet.
    4. fragment: Takes one packet and returns two fragments/segments.

    Mental Model

    • Trigger: A condition that identifies which packets the tree should run on (e.g., [TCP:flags:A]).
    • Action Tree: A binary-tree structure where a trigger pulls a packet into the tree, and the tree describes the modifications.
    • Forest: A collection of action trees. Because Geneva handles inbound and outbound traffic differently, a strategy is composed of two forests: an outbound forest and an inbound forest, separated by the \/ delimiter.
    • Branching: Actions like duplicate and fragment introduce branching. Note that due to Scapy and NFQueue limitations, branching actions are disabled for incoming action forests.

  10. How Geneva plugins work

    master

    Application plugins act as fitness functions for Geneva during evolution, allowing the system to evolve strategies specifically designed to defeat certain types of censorship.

    Plugins are discovered automatically if they are placed in the plugins/ directory of the Geneva repository. Each plugin resides in its own folder named after the plugin.

    There are three types of plugins:

    1. Clients (client.py): Used for client-side evaluation. During client-side evolution, the evaluator starts the engine and then runs the client plugin. During server-side evolution, the evaluator runs the engine on the server-side and starts the client plugin via an SSH session to a remote client worker.
    2. Servers (server.py): [Optional] Used for server-side evaluation. Required if you need to perform evaluation on the server side.
    3. Overriding Plugins (plugin.py): [Optional] Used to customize the evaluator's default behavior. If provided, the evaluator invokes this plugin at the start of strategy evaluation, and the overriding plugin becomes responsible for calling both the client and the server.

  11. How the Geneva engine works

    master

    The strategy engine (engine.py) applies censorship evasion strategies to network connections by capturing traffic to and from a specified port.

    Workflow:

    1. The engine captures all traffic directed to/from the target port.
    2. Packets matching an active trigger are processed through an associated action-tree.
    3. Packets that emerge from the action-tree are then sent on the wire.

    Important Limitation: Due to limitations of scapy and NFQueue, the engine cannot be used to communicate with localhost.

  12. Understand evolve.py argument parsing

    master
    The evolve.py script uses a pass-through argument parsing system. Different components (such as the evaluator or various plugins) define and parse the specific arguments they require. If you run evolve.py --help, the script will aggregate and display the help messages from all relevant components.