https://github.com/ooni/evilgenius
Evil Genius plays the role of the Descartes demon, creating a distorted view of the internet with censorship (it's a censorship simulator)
https://github.com/ooni/evilgenius
Last synced: over 1 year ago
JSON representation
Evil Genius plays the role of the Descartes demon, creating a distorted view of the internet with censorship (it's a censorship simulator)
- Host: GitHub
- URL: https://github.com/ooni/evilgenius
- Owner: ooni
- Created: 2013-06-08T10:00:11.000Z (about 13 years ago)
- Default Branch: master
- Last Pushed: 2014-11-12T14:04:30.000Z (over 11 years ago)
- Last Synced: 2025-04-13T01:28:02.160Z (over 1 year ago)
- Language: Python
- Size: 479 KB
- Stars: 38
- Watchers: 22
- Forks: 11
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# EvilGenius...
... is a general purpose censorship environment simulator.
## What does it do?
To verify that ooniprobe-tests are working correctly, EvilGenius will provide a
series of virtual environments that simulate different censorship techniques
and run the tests against them.
EvilGenius interacts with Vagrant, a developer-oriented interface for headless
VirtualBox.
When run with resources, EvilGenius will assemble a temporary virtual network
in VirtualBox (If you open the VirtualBox GUI when EvilGenius is running, you
can even watch it!) and run commands in it.
## Installation
EvilGenius depends on `python`, `pyyaml` and `vagrant`.
To install EvilGenius, after the dependencies are installed, just
```
git clone ...
```
and you're done.
## Synopsis
```
bin/evilgenius [--help] [--list] -n instrument1 -n instrument2 -c censorship [-v]
[-L logdir] [-w workdir] [-d]
```
## Flags and options
The following flags and options are available in EvilGenius:
* `--help`: Displays usage information
* `--list`: List available resources, i.e. network measurement instruments and
censorship providers
* `-n instrument`: Include a specific network measurement instrument. Currently
about 120 network measurement instruments are supported simultaneously.
* `-c censorship`: Select a specific censorship provider. Currently only one
censorship provider at a time is supported.
* `-v`: enable verbose output
* `-L`: Set log directory. If not specified, this defaults to the working
directory.
* `-w`: Set working Directory. If not specified, EvilGenius will create a
temporary directory according to the conventions of your operating System.
* `-d`: Dry-Run. Write Vagrantfile to STDOUT and exit. Useful for debugging
custom resource descriptor
## Resource Descriptors (How to roll your own)
### Network Measurement Instruments
Network measurement instruments are "probes" that are being run in the censored
environment. To build one, `cd` into the `resources` folder and create a
directory with the name for the new censorship box:
```
cd resources/network-measurement-instruments
mkdir myinstrument
```
Inside the instrument directory, create a yaml file with the filename
`.yml`.
```
touch myinstrument.yml
```
which you now begin to edit with the editor of your choice, `vim`.
Descriptor files are of a certain structure. As a template, you can use the
`ping` and traceroute descriptor files which are fairly basic.
Here's a further example with some explanations
```
# name of the Instrument, Identifies it for the `--list` command
name: Ping
# some description for the probe, appears in the `--list` command
description: Perform a simple ICMP Ping to goatse.cx
# box: defines the name of the Vagrant base box to use.
box: precise32
# This shall be run once when first setting up the network measurement virtual machine
install: sh /scripts/hello.sh
# optional, is run before the install command
before_install:
- echo "Hello, World!"
# optional, is run during the setup process after the network setup
after_install:
- echo "Hello, World!"
# This is the command that executes the network measurment software once
# the whole network has been pulled up.
run: ping -c 10 goatse.cx
```
### Censorship providers
Like network measurement instruments, censorship provider descriptor files
live in the `resources` folder, but since they're not network measurement
instruments, we put them in their own subfolder, namely `censorship-providers`.
We create a new file similar to what we dit with network managenment
instruments above:
```
cd resources/censorship-provider
mkdir myprovider
cd myprovider
touch myprovider.yml
```
The only difference to network measurement instruments is that there is not
one single `run` sections, but start and stop sections where you can put the
start and stop commands for your censorship software. At the moment, they're
not used at all, in the meantime, just put the start command in `after_install`.
Here's an example with some documentation:
```
# name of the censorhip provider, appears in --list output
name: No Censorship
# description of the censorhip provider, appears in --list output
description: Do not perform censorship; use as base for your own providers.
# name of the vagrant base box to be used for this censorship provider
box: precise32
# This is run before the install command
before_install:
- echo "Hello, World!"
# install command
install:
- echo "Hello, World!"
# This is run after the install command and after the network setup
after_install:
- /sbin/sysctl -w net.ipv4.ip_forward=1
- /sbin/iptables -F
- /sbin/iptables --delete-chain
- /sbin/iptables -t nat -F
- /sbin/iptables -t nat --delete-chain
- iptables --table nat --append POSTROUTING --out-interface eth0 -j MASQUERADE
- iptables --append FORWARD --in-interface eth1 -j ACCEPT
- echo "asdf"
# This shall be run every time the censorship vm starts
start: /sbin/sysctl -w net.ipv4.ip_forward=1
# This shall be run every time the censorship vm stops
stop: /sbin/sysctl -w net.ipv4.ip_forward=0
```
### Additional info on descriptors
The descriptors' directories are mounted into the vagrant box as `/script`.
This means you can write shell scripts and put them next to the descriptor
file.
You can execute them from the descriptor file via `/bin/bash /scripts/`.
### Useful strategies for debugging descriptors
Writing resource descriptors can be tricky and time-consuming. Here are some
strategies that should facilitate debugging.
* Start out from a template or very basic descriptor file.
* Make a minimal network configuration, and save the `Vagrantfile` to an empty
directory. then boot the network up by `cd`ing into that directory and
calling `vagrant up`. Now you can watch the log scrolling by and see if
something fails.
* If something breaks and you're not sure why, remove the command from the
descriptor file and boot the network up without it. then `vagrant ssh` into
the box in question and try to execute it by hand.
### Wishlist
It would be nice to have censorship providers for the following types of censorship mechanisms:
* A transparent HTTP proxy (based on squid)
* NAT traversal
* HTTP proxy blocking certain sites
* DNS based censorship