README.md

# DNSCensorBreaker
DNSCensorBreaker is a python tool that acts as a proxy and implements DNS censorship evasion techniques.
The tool is implemented to bypass DNS censorship of the Great Fire Wall in China.
Currently, GFWatch Comparison, Encrypted DNS, and TCP Fragmentation are implemented.
The techniques can be activated separately.

This tool should be run locally to circumvent the DNS censorship successfully.
It can be set up as the standard DNS resolver so that every DNS message is sent to this tool.

# Requirements
- python3
  - `sudo apt install python3`

All requirements below can be installed with `pip3 install -r requirements.txt`
- dnspython
- requests
- pyyaml
- httpx
- httpcore
- h2
- aioquic
  

# Usage

```
python3 main.py -h
      
usage: main.py [-h] [--debug | --no-debug] [--timeout TIMEOUT] [--host HOST] [--port PORT] [--dns_server DNS_SERVER]
               [--server_port SERVER_PORT] [--strategy {GFWatch,Encrypted,PreferEncrypted,TCPFragmentation}]
               [--encryption_protocol {DoT,DoH,DoQ,FindUsable}]

Optional app description

options:
  -h, --help            show this help message and exit
  --debug, --no-debug   Turns on debugging
  --timeout TIMEOUT     Connection timeout in seconds
  --host HOST           Address the proxy server runs on
  --port PORT           Port the proxy server runs on (default 5533)
  --dns_server DNS_SERVER
                        Defines the dns server that should be used. If the encryption protocol is set to FindUsable,
                        this field will be ignored when the server is blocked and a working server will be determined.
  --server_port SERVER_PORT
                        The port of the dns server. For normal UDP queries this is port 53.
  --strategy {GFWatch,Encrypted,PreferEncrypted,TCPFragmentation}
                        Which type of evasion strategy should be used. GFWatch comparison, Encrypted DNS, TCP
                        fragmentation, or prefer encrypted DNS with fallback to GFWatch comparison.
  --encryption_protocol {DoT,DoH,DoQ,FindUsable}
                        Which encryption protocol should be used for encrypted DNS. Only usable when the
                        evasion_strategy uses encrypted DNS. FindUsable searches for a usable protocol.
```

## Settings

### -- debug
Turns on debugging statements.

### --timeout
The timeout of the underlying sockets, which defines how long a connection is hold or waited for.
This timeout also specifies the exit time of the tool, because it waits for all sockets to be closed. 


### --host
The host on which DNSCensorBreaker listens for incoming connections.

### --port
The port on which DNSCensorBreaker listens for incoming connections. By default, this is set to 5533.

### --dns_server
Defines the DNS server that should be used. If the encryption protocol is set to FindUsable, this field will be ignored
when the server is blocked and a working server will be determined.

### --server_port
Defines the port of the DNS server that is used for DNS resolving. For normal DNS queries over UDP this is set to port 53.

### --strategy
Defines the evasion strategy that is used to bypass DNS censorship. Available options: GFWatch comparison, Encrypted DNS
, TCPFragmentation, or prefer encrypted DNS with fallback to GFWatch comparison.

### --encryption_protocol 
Which encryption protocol should be used for encrypted DNS. Only usable when the evasion_strategy is set to encrypted 
DNS. FindUsable searches for a usable protocol.


## Default Configuration

To automatically set default configuration, we added the default_config.yml file. In this file the default connection 
and strategy is defined that is used when no other parameter is provided. 

## Examples

`python3 main.py` Launches DNSCensorBreaker with the default configuration specified in the default_config.yml. 

`python3 main.py --host 127.0.0.1 --port 4444` Launches DNSCensorBreaker locally on port 4444 and uses the strategy 
defined in the default configuration.

`python3 main.py --dns_server 1.1.1.1 --server_port 53 --strategy GFWatch` Starts the tool and uses the Cloudflare DNS 
resolver with the GFWatch comparison strategy.

`python3 main.py --dns_server 8.8.8.8 --server_port 853 --strategy Encrypted --encryption_protocol DoT` Launches the 
tool and uses a DoT connection to the Google DNS resolver. 

`python3 main.py --dns_server 8.8.8.8 --server_port 853 --strategy PreferEncrypted --encryption_protocol DoT` Launches 
tool and tries to establish a connection to the DoT endpoint of the Google resolver. If it is not reachable it falls 
back to the GFWatch comparison strategy.

`python3 main.py --strategy PreferEncrypted --encryption_protocol FindUsable` Launches the tool in the availability 
check mode. It tries to search for an encrypted connection. If it found one this will be used. If no encrypted 
connection could be established, the tool falls back to the GFWatch comparison.

`python3 main.py --debug` Launches the tool in the debug mode.

## Testing

Setup DNSCensorBreaker with 
```sh
python3 main.py --port 4444 --strategy GFWatch 
```

test it by sending a DNS query via dig or another dns query tool
```sh
dig @127.0.0.1 google.com -p 5533
```

When using Wireshark, you can see the injected DNS response from the GFW and the real response that is returned by the 
tool.