From ed75909ea11f592f451b9860c2b21583a4f02033 Mon Sep 17 00:00:00 2001 From: MicroMike Date: Tue, 12 Jul 2016 10:39:35 +0800 Subject: [PATCH 1/2] Update Readme. - Add Feature List - Add Viewer List - Change some of the description to wiki page. --- README.md | 150 +++++++++++++++++------------------------------------- 1 file changed, 47 insertions(+), 103 deletions(-) diff --git a/README.md b/README.md index bd0504e..98ea0d1 100644 --- a/README.md +++ b/README.md @@ -1,131 +1,75 @@ -# 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. [![Build Status](https://travis-ci.org/mike820324/microProxy.svg?branch=master)](https://travis-ci.org/mike820324/microProxy) [![Coverage Status](https://coveralls.io/repos/github/mike820324/microProxy/badge.svg?branch=master)](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: - -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. +## Features: +- Proxy Mode: + - SOCKS5 Proxy + - Transparent Proxy(Linux Only) -```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**. -There are two sub-service for our binary which are +The python version we are using is version 2.7.10. -- 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). From 4cdc6ebcb424ad5784d265f9117383f052432938 Mon Sep 17 00:00:00 2001 From: mike820324 Date: Sun, 31 Jul 2016 14:23:09 +0800 Subject: [PATCH 2/2] Update README. --- README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 98ea0d1..820671e 100644 --- a/README.md +++ b/README.md @@ -36,8 +36,9 @@ For more in depth information about our architecture design, please refer to the ## System Requirement: **microProxy** can run in both **Linux** and **MacOS**. +> Note: The transparent proxy mode can only work in Linux. -The python version we are using is version 2.7.10. +In order to let http2 protocol works properly, the openssl version **1.0.2.h** (alpn support)is required. ## Installation