{"id":20450070,"url":"https://github.com/ooni/evilgenius","last_synced_at":"2025-04-13T02:10:39.357Z","repository":{"id":8857253,"uuid":"10566952","full_name":"ooni/EvilGenius","owner":"ooni","description":"Evil Genius plays the role of the Descartes demon, creating a distorted view of the internet with censorship (it's a censorship simulator)","archived":false,"fork":false,"pushed_at":"2014-11-12T14:04:30.000Z","size":491,"stargazers_count":38,"open_issues_count":1,"forks_count":11,"subscribers_count":22,"default_branch":"master","last_synced_at":"2025-04-13T01:28:02.160Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ooni.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2013-06-08T10:00:11.000Z","updated_at":"2024-07-12T00:39:27.000Z","dependencies_parsed_at":"2022-08-27T20:52:01.511Z","dependency_job_id":null,"html_url":"https://github.com/ooni/EvilGenius","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ooni%2FEvilGenius","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ooni%2FEvilGenius/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ooni%2FEvilGenius/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ooni%2FEvilGenius/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ooni","download_url":"https://codeload.github.com/ooni/EvilGenius/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248654090,"owners_count":21140236,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-15T10:50:10.531Z","updated_at":"2025-04-13T02:10:39.333Z","avatar_url":"https://github.com/ooni.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# EvilGenius...\n\n... is a general purpose censorship environment simulator.\n\n## What does it do?\n\nTo verify that ooniprobe-tests are working correctly, EvilGenius will provide a\nseries of virtual environments that simulate different censorship techniques\nand run the tests against them.\n\nEvilGenius interacts with Vagrant, a developer-oriented interface for headless\nVirtualBox.\n\nWhen run with resources, EvilGenius will assemble a temporary virtual network\nin VirtualBox (If you open the VirtualBox GUI when EvilGenius is running, you\ncan even watch it!) and run commands in it.\n\n## Installation\n\nEvilGenius depends on `python`, `pyyaml` and `vagrant`.\n\nTo install EvilGenius, after the dependencies are installed, just\n\n```\ngit clone ...\n```\n\nand you're done.\n\n## Synopsis\n\n```\nbin/evilgenius [--help] [--list] -n instrument1 -n instrument2 -c censorship [-v]\n    [-L logdir] [-w workdir] [-d]\n```\n\n## Flags and options\n\nThe following flags and options are available in EvilGenius:\n* `--help`: Displays usage information\n* `--list`: List available resources, i.e. network measurement instruments and\n    censorship providers\n* `-n instrument`: Include a specific network measurement instrument. Currently\n    about 120 network measurement instruments are supported simultaneously.\n* `-c censorship`: Select a specific censorship provider. Currently only one\n    censorship provider at a time is supported.\n* `-v`: enable verbose output\n* `-L`: Set log directory. If not specified, this defaults to the working \n    directory.\n* `-w`: Set working Directory. If not specified, EvilGenius will create a\n    temporary directory according to the conventions of your operating System.\n* `-d`: Dry-Run. Write Vagrantfile to STDOUT and exit. Useful for debugging\n    custom resource descriptor\n\n## Resource Descriptors (How to roll your own)\n\n### Network Measurement Instruments\n\nNetwork measurement instruments are \"probes\" that are being run in the censored\nenvironment. To build one, `cd` into the `resources` folder and create a\ndirectory with the name for the new censorship box:\n\n```\ncd resources/network-measurement-instruments\nmkdir myinstrument\n```\n\nInside the instrument directory, create a yaml file with the filename \n`\u003cname\u003e.yml`.\n\n```\ntouch myinstrument.yml\n```\n\nwhich you now begin to edit with the editor of your choice, `vim`.\n\nDescriptor files are of a certain structure. As a template, you can use the\n`ping` and traceroute descriptor files which are fairly basic.\n\nHere's a further example with some explanations\n\n```\n# name of the Instrument, Identifies it for the `--list` command\nname: Ping\n# some description for the probe, appears in the `--list` command\ndescription: Perform a simple ICMP Ping to goatse.cx\n# box: defines the name of the Vagrant base box to use.\nbox: precise32\n\n# This shall be run once when first setting up the network measurement virtual machine\ninstall: sh /scripts/hello.sh\n\n# optional, is run before the install command\nbefore_install: \n        - echo \"Hello, World!\"\n# optional, is run during the setup process after the network setup\nafter_install:\n        - echo \"Hello, World!\"\n\n# This is the command that executes the network measurment software once\n# the whole network has been pulled up. \nrun: ping -c 10 goatse.cx\n```\n\n### Censorship providers\n\nLike network measurement instruments, censorship provider descriptor files\nlive in the `resources` folder, but since they're not network measurement\ninstruments, we put them in their own subfolder, namely `censorship-providers`.\n\nWe create a new file similar to what we dit with network managenment \ninstruments above:\n\n```\ncd resources/censorship-provider\nmkdir myprovider\ncd myprovider\ntouch myprovider.yml\n```\n\nThe only difference to network measurement instruments is that there is not\none single `run` sections, but start and stop sections where you can put the\nstart and stop commands for your censorship software. At the moment, they're\nnot used at all, in the meantime, just put the start command in `after_install`.\n\nHere's an example with some documentation:\n\n```\n# name of the censorhip provider, appears in --list output\nname: No Censorship\n# description of the censorhip provider, appears in --list output\ndescription: Do not perform censorship; use as base for your own providers.\n# name of the vagrant base box to be used for this censorship provider\nbox: precise32\n\n# This is run before the install command\nbefore_install:\n  - echo \"Hello, World!\"\n\n# install command\ninstall:\n  - echo \"Hello, World!\"\n\n# This is run after the install command and after the network setup \nafter_install:\n  - /sbin/sysctl -w net.ipv4.ip_forward=1\n  - /sbin/iptables -F\n  - /sbin/iptables --delete-chain\n  - /sbin/iptables -t nat -F\n  - /sbin/iptables -t nat --delete-chain\n  - iptables --table nat --append POSTROUTING --out-interface eth0 -j MASQUERADE\n  - iptables --append FORWARD --in-interface eth1 -j ACCEPT\n  - echo \"asdf\"\n\n# This shall be run every time the censorship vm starts\nstart: /sbin/sysctl -w net.ipv4.ip_forward=1\n\n# This shall be run every time the censorship vm stops\nstop: /sbin/sysctl -w net.ipv4.ip_forward=0\n```\n### Additional info on descriptors\n\nThe descriptors' directories are mounted into the vagrant box as `/script`.\nThis means you can write shell scripts and put them next to the descriptor\nfile.\n\nYou can execute them from the descriptor file via `/bin/bash /scripts/\u003cscript\u003e`.\n\n### Useful strategies for debugging descriptors\n\nWriting resource descriptors can be tricky and time-consuming. Here are some\nstrategies that should facilitate debugging.\n\n  * Start out from a template or very basic descriptor file.\n  * Make a minimal network configuration, and save the `Vagrantfile` to an empty\n    directory. then boot the network up by `cd`ing into that directory and\n    calling `vagrant up`. Now you can watch the log scrolling by and see if\n    something fails.\n  * If something breaks and you're not sure why, remove the command from the\n    descriptor file and boot the network up without it. then `vagrant ssh` into\n    the box in question and try to execute it by hand.\n\n### Wishlist\n\nIt would be nice to have censorship providers for the following types of censorship mechanisms:\n\n\n* A transparent HTTP proxy (based on squid)\n\n* NAT traversal\n\n* HTTP proxy blocking certain sites\n\n* DNS based censorship\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fooni%2Fevilgenius","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fooni%2Fevilgenius","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fooni%2Fevilgenius/lists"}