From b462143791c972052f3c70faeb2cdcf3c33473ca Mon Sep 17 00:00:00 2001 From: twisteroidambassador Date: Wed, 28 Nov 2018 22:09:37 +0800 Subject: [PATCH] Update README with info on C++ version. --- README.md | 105 ++++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 78 insertions(+), 27 deletions(-) diff --git a/README.md b/README.md index ebfd592..2c044e1 100644 --- a/README.md +++ b/README.md @@ -23,21 +23,9 @@ network traffic* - Profit! -## System Requirements - -Retroflect runs on Windows. It requires Python 3.6.x and -[pydivert](https://pypi.org/project/pydivert/). - -Pydivert doesn't seem to support Python 3.7 yet, and retroflect uses -features introduced in 3.6, so that's the only version supported at the -time. - -(That said, it shouldn't be difficult to backport retroflect. -Replace f-strings with `format()` and it should run on 3.5. Remove -type annotations and it should run on 3.4.) +## Theory - -## Features +### Design Goal Retroflect reflects outgoing network traffic back at the sender. When retroflect is running on a system with one or more @@ -51,7 +39,7 @@ Additionally, retroflect can also be configured with zero or more drops any incoming traffic destined for these ports. -## Usage +### Use Case Retroflect is designed for one use case: running a server on localhost for clients on the same system, while disguising it as a server on @@ -79,7 +67,7 @@ To use retroflect for this purpose, follow these steps: * Direct client software to connect to `reflect-address:server-port` -### Choose reflect address(es) +### Choosing reflect address(es) A reflect address must meet the following requirements: @@ -104,14 +92,12 @@ connectivity, there probably is no IPv4 default route, and an IPv4 reflect address won't work. -### Bind server to wildcard address +### Binding server to wildcard address The server running on the system must be bound to the wildcard address (`0.0.0.0` or `::`) in order to receive reflected traffic, which will appear to come from the reflect address. -Make sure Windows Firewall is not blocking the server. - Binding to the wildcard address does mean that other computers on the network may connect to the server as well. If this is not desired, you can specify the server's port(s) as shield ports when running @@ -119,16 +105,75 @@ retroflect, which will drop incoming traffic towards those ports and protect the server. +## Implementation + +This repository contains two implementations of retroflect: a Python +version, and a C++ version. The C++ version is recommended, since it +uses a more up-to-date version of WinDivert, and should have better +performance. + + +### System Requirements + +#### C++ + +Using the C++ version of retroflect downloaded from the +[Releases page](https://github.com/twisteroidambassador/retroflect/releases) +does not require any 3rd-party dependency, since the required WinDivert +drivers are bundled in. + +Building the C++ version of retroflect requires Visual Studio and +[WinDivert 1.4.3](https://reqrypt.org/windivert.html). I used Visual +Studio 2017 Community to develop and build the code; other versions +may also work. + + +#### Python + +The Python version of retroflect requires Python 3.6.x and +[pydivert](https://pypi.org/project/pydivert/). +Pydivert doesn't seem to support Python 3.7 yet, and retroflect uses +features introduced in 3.6, so that's the only version supported at the +time. +(That said, it shouldn't be difficult to backport retroflect. +Replace f-strings with `format()` and it should run on 3.5. Remove +type annotations and it should run on 3.4.) +Pydivert bundles WinDivert 1.3, so no separate WinDivert is +required. + + ### Running retroflect +#### C++ + +Retroflect must run with Administrator privileges. It will request +UAC elevation if required. Just run: + + retroflect.exe ... + +Multiple reflect addresses and shield ports may be specified in any +order. + +When starting, the specified reflect addresses and shield ports are +printed to the console, then "Reflection in progress..." is printed. +`Ctrl+C` can be used to stop retroflect. + + +#### Python + Retroflect must be run with Administrator privileges. Open an Administrator cmd prompt or powershell prompt and run: retroflect.py [-s ] -Normally there won't be any console output. For help about command line arguments, run `retroflect.py -h`. +Normally there won't be any console output. For help about command line +arguments, run `retroflect.py -h`. + +`Ctrl+C` may not work to stop retroflect. Try `Break` or `Ctrl+Break`. -Once it's running, any client software making a connection to +#### --- + +Once retroflect is running, any client software making a connection to `reflect-address:server-port` will actually connect to the server running on localhost. For the server, it looks like the client is connecting from the reflect address. Neither the client nor the server @@ -136,11 +181,17 @@ will realize that the other party is running on the same system. Mission accomplished! -## Known issues +### Known issues + +The C++ and Python versions of retroflect currently have different +behavior. The C++ version only reflects TCP traffic towards +reflect addresses, and only shields incoming TCP traffic towards shield +ports. The Python version reflects all network traffic towards reflect +addresses, but also only shields incoming TCP traffic. -If a server port is shielded, any attempt to access it via the +Also, with the Python version, +when a server port is shielded any attempt to access it via the localhost address (`127.0.0.1:server-port`, `[::1]:server-port`, etc.) -may also fail. This is because pydivert still uses WinDivert 1.3, -and WinDivert only added the "loopback" filter in 1.4, so loopback -traffic to shield ports are also filtered and dropped. Re-injecting -loopback packets doesn't seem to work properly, either. +will also fail. This is because pydivert still uses WinDivert 1.3, +and that version does not handle loopback traffic well. The C++ version +does allow loopback traffic towards shield ports.