-
Notifications
You must be signed in to change notification settings - Fork 3
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #109 from mike820324/Readme-Enhancement-#76
Update README. - move some of the content to wiki page. - update project description. - add feature description.
- Loading branch information
Showing
1 changed file
with
48 additions
and
103 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,131 +1,76 @@ | ||
| # MicroProxy | ||
|
|
||
| MicroProxy is a http/https traffic interceptor. | ||
| # microProxy | ||
|
|
||
| **microProxy** is a http/https traffic interceptor which can help you debug with http/https based network traffic. | ||
| This project is highly inspired by [mitmproxy](https://github.com/mitmproxy/mitmproxy), | ||
| but we take some different approach compare to mitmproxy. | ||
| but with some different [architecture design](https://github.com/mike820324/microProxy/wiki/System-Architecture). | ||
|
|
||
| In MicroProxy, we seperate the proxy and viewing into different process and using a message queue to communicate with each other. | ||
| By using this kind of approach, we can easily implement different kind of viewing component without changing the proxy code base. | ||
| Moreover, we can also open multiple viewing process to listen to the same MicroProxy server. | ||
|
|
||
| For more in depth information about our architecture design, please refer to the [wiki page](https://github.com/mike820324/microProxy/wiki). | ||
| > Note: We are still in a very earyly stage and as a result, the interface will be changed. | ||
| [](https://travis-ci.org/mike820324/microProxy) | ||
| [](https://coveralls.io/github/mike820324/microProxy?branch=master) | ||
|
|
||
| ## System Requirement: | ||
| We have tested MicroProxy under **Linux** and **MacOS**. | ||
| The python version we are using is version 2.7.10. | ||
|
|
||
| > Note: *transparent proxy mode* can only work in Linux machine. | ||
| ## Environment Setup: | ||
| ## Features: | ||
| - Proxy Mode: | ||
| - SOCKS5 Proxy | ||
| - Transparent Proxy(Linux Only) | ||
|
|
||
| In this section, we will show you the steps to setup the project properly. | ||
|
|
||
| ### Project Installation | ||
|
|
||
| Since we do not have setup.py yet, you can not use **setuptool** to install this project. | ||
| Currently, you have to clone the project and use pip to install the requirements. | ||
|
|
||
| ```bash | ||
| git clone https://github.com/mike820324/microProxy.git | ||
| cd microProxy | ||
| pip install -r requirements.txt | ||
| ``` | ||
|
|
||
| ### Socks Proxy Setup: | ||
|
|
||
| Setting up the socks proxy is very easy. | ||
| Just type the following command, and config your browser to use socks proxy with the same port. | ||
|
|
||
| ```shell | ||
| python main.py proxy --host=127.0.0.1 --port=8080 | ||
| ``` | ||
| - Protocol Support: | ||
| - HTTP | ||
| - HTTPS | ||
| - HTTP2 (vis alpn, HTTP Upgrade is not supported) | ||
|
|
||
| ### Transparent Proxy Setup: | ||
| - Flexible Viewer Design: | ||
| - Viewer can connect to proxy with different machine. | ||
| - Support multiple viewer connect to the same proxy instance. | ||
| - Implement your own viewer by following the Viewer communication mechanism. | ||
|
|
||
| There may be two possible scenario for transparent proxy setup. | ||
| - Plugin System (still in very earyly stage): | ||
| - Support external script to modify the Request/Response content. | ||
|
|
||
| #### In the same machine: | ||
| Make sure that your microproxy is run in the different uid or gid. | ||
| Let's assume the microproxy is running in **proxy** uid. | ||
| ## Viewer Implementation List: | ||
| - Console Viwer: Simple console dump viewer. | ||
| - TUI Viwer: Terminal UI viewer which used [gviewer](https://github.com/chhsiao90/gviewer). | ||
| - [GUI Viewer](https://github.com/mike820324/microProxy-GUI): Graphic UI written in node.js and electron. | ||
|
|
||
| Type the following command to setup the transparent proxy for localhost only. | ||
|
|
||
| ```shell | ||
| python main.py proxy --mode=transparent --port=8080 | ||
| sudo iptables -t nat -A OUTPUT -p tcp -m owner ! --uid-owner proxy --dport 80 -j REDIRECT --to-port 8080 | ||
| ``` | ||
|
|
||
| #### In different machine: | ||
|
|
||
| ```shell | ||
| python main.py proxy --mode=transparent --port=8080 | ||
| sudo sysctl -w net.ipv4.ip_forward=1 | ||
| sudo iptables -t nat -A OUTPUT -p tcp --dport 80 -j REDIRECT --to-port 8080 | ||
| ``` | ||
|
|
||
| Now set the default gateway of the client machine to the machine that the microProxy is running on. | ||
|
|
||
|
|
||
| ## Command Line Options: | ||
| ## System Requirement: | ||
| **microProxy** can run in both **Linux** and **MacOS**. | ||
| > Note: The transparent proxy mode can only work in Linux. | ||
| There are two sub-service for our binary which are | ||
| In order to let http2 protocol works properly, the openssl version **1.0.2.h** (alpn support)is required. | ||
|
|
||
| - Proxy: Enable the proxy server. | ||
| - Viewer: Open the viewer to view the http traffic. | ||
| ## Installation | ||
|
|
||
| Each sub-service has there are options. | ||
| This project is not update to pypi yet. | ||
| Therefore, to intall this project, please follow the following steps. | ||
|
|
||
| ### Proxy: | ||
| ```bash | ||
| git clone https://github.com/mike820324/microProxy.git | ||
| cd microProxy | ||
|
|
||
| The following are the command line options for Proxy service. | ||
| # install proxy dependency | ||
| pip install . | ||
|
|
||
| * --host: specify the proxy host. | ||
| * --port: specify the proxy listening port. | ||
| * --mode: specify the proxy mode. Currently we have supported two diffenty mode, **socks proxy** and **transparent proxy**. | ||
| * --http-port: specify the additional http port. | ||
| * --https-port: specify the additional https port. | ||
| * --cert-file: specify the certificate file. | ||
| * --key-file: specify the private key file. | ||
| * --viewer-channel: specify the viewer channel. For example, tcp://*:5580 | ||
| # install viewer dependency | ||
| pip install .[viewer] | ||
|
|
||
| For example, | ||
| ```shell | ||
| python main.py proxy --host=127.0.0.1 --port=8080 --mode=socks --http-port=5580 5581 5582 --https-port=5583 5584 5585 | ||
| python main.py proxy --host=127.0.0.1 --port=8080 --mode=transparent | ||
| # install dev dependency | ||
| pip install .[develop] | ||
| ``` | ||
| ### Viewer: | ||
|
|
||
| The following are the command line options for Viewer service. | ||
| To run the proxy, simply type the following command. | ||
|
|
||
| * --mode: specify the viewer mode. Currently we only support log viewer. | ||
| * --viewer-channel: specify the viewer channel. For example, tcp://127.0.0.1:5580 | ||
| ```bash | ||
| # start proxy server | ||
| microproxy proxy --viewer-channel tcp://127.0.0.1:5581 | ||
|
|
||
| For example, | ||
| ```shell | ||
| python main.py viewer --mode=log | ||
| ``` | ||
| # start tui-viewer | ||
| microproxy tui-viewer --viewer-channel tcp://127.0.0.1:5581 | ||
|
|
||
| ## Configuration File: | ||
| Currently, we only support the ini config format. | ||
|
|
||
| The following is an example config file. | ||
| ```ini | ||
| [proxy] | ||
| host=127.0.0.1 | ||
| port=5580 | ||
| mode=socks | ||
| http.port=5581,5582,5583 | ||
| https.port=5584 | ||
| certfile=/tmp/cert.crt | ||
| keyfile=/tmp/cert.key | ||
| viewer.channel=tcp://*:5585 | ||
|
|
||
| [viewer] | ||
| mode=log | ||
| viewer.channel=tcp://127.0.0.1:5585 | ||
| # start console-viewer | ||
| microproxy console-viewer --viewer-channel tcp://127.0.0.1:5581 | ||
| ``` | ||
|
|
||
| For more information about command line options and configurations, | ||
| please refer to the [wiki page](https://github.com/mike820324/microProxy/wiki/Command-Line-Options-and-Config-Files). |