readme

README.md

@@ -1,72 +1,157 @@
 # go-mitmproxy
 
-[English](./README_EN.md)
+[简体中文](./README_CN.md)
 
-Golang 版本的 [mitmproxy](https://mitmproxy.org/)。
+`go-mitmproxy` is a Golang implementation of [mitmproxy](https://mitmproxy.org/) that supports man-in-the-middle attacks and parsing, monitoring, and tampering with HTTP/HTTPS traffic.
 
-用 Golang 实现的中间人攻击（[Man-in-the-middle](https://en.wikipedia.org/wiki/Man-in-the-middle_attack)），解析、监测、篡改 HTTP/HTTPS 流量。
+## Key features
 
-## 特点
+- Parses HTTP/HTTPS traffic and displays traffic details via a [web interface](#web-interface).
+- Supports a [plugin mechanism](#adding-functionality-by-developing-plugins) for easily extending functionality. Various event hooks can be found in the [examples](./examples) directory.
+- HTTPS certificate handling is compatible with [mitmproxy](https://mitmproxy.org/) and stored in the `~/.mitmproxy` folder. If the root certificate is already trusted from a previous use of `mitmproxy`, `go-mitmproxy` can use it directly.
+- Refer to the [configuration documentation](#additional-parameters) for more features.
 
-- HTTPS 证书相关逻辑参考 [mitmproxy](https://mitmproxy.org/) 且与之兼容，根证书也保存在 `~/.mitmproxy` 文件夹中，如果之前用过 `mitmproxy` 且根证书已经安装信任，则此 `go-mitmproxy` 可以直接使用
+## Unsupported features
-- 支持插件机制，很方便扩展自己需要的功能，可参考 [examples](./examples)
-- 性能优势
-  - Golang 天生的性能优势
-  - 在进程内存中转发解析 HTTPS 流量，不需通过 tcp 端口 或 unix socket 等进程间通信
-  - 生成不同域名证书时使用 LRU 缓存，避免重复计算
-- 通过环境变量 `SSLKEYLOGFILE` 支持 `Wireshark` 解析分析流量
-- 上传/下载大文件时支持流式传输
-- Web 界面
 
-## 安装
+- Only supports setting the proxy manually in the client, not transparent proxy mode.
+- Currently does not support HTTP/2 protocol parsing or WebSocket protocol parsing.
 
-```
+> For more information on the difference between manually setting a proxy and transparent proxy mode, please refer to the mitmproxy documentation for the Python version: [How mitmproxy works](https://docs.mitmproxy.org/stable/concepts-howmitmproxyworks/). go-mitmproxy currently supports "Explicit HTTP" and "Explicit HTTPS" as mentioned in the article.
+
+## Command Line Tool
+
+### Installation
+
+```bash
 go install github.com/lqqyt2423/go-mitmproxy/cmd/go-mitmproxy@latest
 ```
 
-## 命令行使用
+### Usage
 
-### 启动
+Use the following command to start the go-mitmproxy proxy server:
 
-```
+```bash
 go-mitmproxy
 ```
 
-启动后，HTTP 代理地址默认为 9080 端口，Web 界面默认在 9081 端口。
+After starting, the HTTP proxy address is set to port 9080 by default, and the web interface is set to port 9081 by default.
 
-首次启动后需按照证书以解析 HTTPS 流量，证书会在首次启动命令后自动生成，路径为 `~/.mitmproxy/mitmproxy-ca-cert.pem`。可参考此链接安装：[About Certificates](https://docs.mitmproxy.org/stable/concepts-certificates/)。
+The certificate needs to be installed after the first startup to parse HTTPS traffic. The certificate will be automatically generated after the first startup command and stored in `~/.mitmproxy/mitmproxy-ca-cert.pem`. Installation steps can be found in the Python mitmproxy documentation: [About Certificates](https://docs.mitmproxy.org/stable/concepts-certificates/).
 
-### 启动参数
+### Additional Parameters
 
+ou can use the following command to view more parameters of go-mitmproxy:
+
+```bash
+go-mitmproxy -h
 ```
+
+```txt
 Usage of go-mitmproxy:
   -addr string
     	proxy listen addr (default ":9080")
+  -allow_hosts value
+    	a list of allow hosts
   -cert_path string
     	path of generate cert files
   -debug int
     	debug mode: 1 - print debug log, 2 - show debug from
-  -dump string
+  -f string
-    	dump filename
+    	Read configuration from file by passing in the file path of a JSON configuration file.
-  -dump_level int
+  -ignore_hosts value
-    	dump level: 0 - header, 1 - header + body
+    	a list of ignore hosts
-  -mapper_dir string
-    	mapper files dirpath
   -ssl_insecure
     	not verify upstream server SSL/TLS certificates.
   -version
-    	show version
+    	show go-mitmproxy version
   -web_addr string
     	web interface listen addr (default ":9081")
 ```
 
-## 作为包引入
+## Importing as a package for developing functionalities
+
+### Simple Example
+
+```golang
+package main
+
+import (
+	"log"
+
+	"github.com/lqqyt2423/go-mitmproxy/proxy"
+)
+
+func main() {
+	opts := &proxy.Options{
+		Addr:              ":9080",
+		StreamLargeBodies: 1024 * 1024 * 5,
+	}
+
+	p, err := proxy.NewProxy(opts)
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	log.Fatal(p.Start())
+}
+```
+
+### Adding Functionality by Developing Plugins
+
+Refer to the [examples](./examples) for adding your own plugins by implementing the `AddAddon` method.
+
+The following are the currently supported event nodes:
+
+```golang
+type Addon interface {
+	// A client has connected to mitmproxy. Note that a connection can correspond to multiple HTTP requests.
+	ClientConnected(*ClientConn)
+
+	// A client connection has been closed (either by us or the client).
+	ClientDisconnected(*ClientConn)
+
+	// Mitmproxy has connected to a server.
+	ServerConnected(*ConnContext)
+
+	// A server connection has been closed (either by us or the server).
+	ServerDisconnected(*ConnContext)
+
+	// The TLS handshake with the server has been completed successfully.
+	TlsEstablishedServer(*ConnContext)
+
+	// HTTP request headers were successfully read. At this point, the body is empty.
+	Requestheaders(*Flow)
+
+	// The full HTTP request has been read.
+	Request(*Flow)
+
+	// HTTP response headers were successfully read. At this point, the body is empty.
+	Responseheaders(*Flow)
+
+	// The full HTTP response has been read.
+	Response(*Flow)
+
+	// Stream request body modifier
+	StreamRequestModifier(*Flow, io.Reader) io.Reader
+
+	// Stream response body modifier
+	StreamResponseModifier(*Flow, io.Reader) io.Reader
+}
+```
+
+## WEB Interface
+
+You can access the web interface at http://localhost:9081/ using a web browser.
 
-参考 [cmd/go-mitmproxy/main.go](./cmd/go-mitmproxy/main.go)，可通过自己实现 `AddAddon` 方法添加自己实现的插件。
+### Features
 
-更多示例可参考 [examples](./examples)
+- View detailed information of HTTP/HTTPS requests
+- Supports formatted preview of JSON requests/responses
+- Supports binary mode to view response body
+- Supports advanced filtering rules
+- Supports request breakpoint function
 
-## Web 界面
+### Screenshot Examples
 
 ![](./assets/web-1.png)
 
@@ -74,11 +159,6 @@ Usage of go-mitmproxy:
 
 ![](./assets/web-3.png)
 
-## TODO
-
-- [ ] 支持 http2 协议
-- [ ] 支持解析 websocket
-
 ## License
 
 [MIT License](./LICENSE)

README_CN.md

@@ -0,0 +1,164 @@
+# go-mitmproxy
+
+[English](./README.md)
+
+`go-mitmproxy` 是一个用 Golang 实现的 [mitmproxy](https://mitmproxy.org/)，支持中间人攻击（Man-in-the-middle）并解析、监测、篡改 HTTP/HTTPS 流量。
+
+## 主要功能
+
+- 解析 HTTP/HTTPS 流量，可通过 [WEB 界面](#web-界面)查看流量详情。
+- 支持[插件机制](#通过开发插件添加功能)，方便扩展自己需要的功能。多种事件 HOOK 可参考 [examples](./examples)。
+- HTTPS 证书相关逻辑与 [mitmproxy](https://mitmproxy.org/) 兼容，并保存在 `~/.mitmproxy` 文件夹中。如果之前已经用过 `mitmproxy` 并安装信任了根证书，则 `go-mitmproxy` 可以直接使用。
+- 更多功能请参考[配置文档](#更多参数)。
+
+## 暂未实现的功能
+
+- 只支持客户端显示设置代理，不支持透明代理模式。
+- 暂不支持 http/2 协议解析和 websocket 协议解析。
+
+> 如需了解显示设置代理和透明代理模式的区别，请参考 Python 版本的 mitmproxy 文档：[How mitmproxy works](https://docs.mitmproxy.org/stable/concepts-howmitmproxyworks/)。`go-mitmproxy` 目前支持文中提到的『Explicit HTTP』和『Explicit HTTPS』。
+
+## 命令行工具
+
+### 安装
+
+```bash
+go install github.com/lqqyt2423/go-mitmproxy/cmd/go-mitmproxy@latest
+```
+
+### 使用
+
+使用以下命令启动 go-mitmproxy 代理服务器：
+
+```bash
+go-mitmproxy
+```
+
+启动后，HTTP 代理地址默认为 9080 端口，Web 界面默认在 9081 端口。
+
+首次启动后需安装证书以解析 HTTPS 流量，证书会在首次启动命令后自动生成，路径为 `~/.mitmproxy/mitmproxy-ca-cert.pem`。安装步骤可参考 Python mitmproxy 文档：[About Certificates](https://docs.mitmproxy.org/stable/concepts-certificates/)。
+
+### 更多参数
+
+可以使用以下命令查看 go-mitmproxy 的更多参数：
+
+```bash
+go-mitmproxy -h
+```
+
+```txt
+Usage of go-mitmproxy:
+  -addr string
+    	代理监听地址 (默认值为 ":9080")
+  -allow_hosts []string
+    	HTTPS解析域名白名单
+  -cert_path string
+    	生成证书文件路径
+  -debug int
+    	调试模式：1-打印调试日志，2-显示调试来源
+  -f string
+    	从文件名读取配置，传入json配置文件地址
+  -ignore_hosts value
+    	HTTPS解析域名黑名单
+  -ssl_insecure
+    	不验证上游服务器的 SSL/TLS 证书
+  -version
+    	显示 go-mitmproxy 版本
+  -web_addr string
+    	web 界面监听地址 (默认值为 ":9081")
+```
+
+## 作为包引入开发功能
+
+### 简单示例
+
+```golang
+package main
+
+import (
+	"log"
+
+	"github.com/lqqyt2423/go-mitmproxy/proxy"
+)
+
+func main() {
+	opts := &proxy.Options{
+		Addr:              ":9080",
+		StreamLargeBodies: 1024 * 1024 * 5,
+	}
+
+	p, err := proxy.NewProxy(opts)
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	log.Fatal(p.Start())
+}
+```
+
+### 通过开发插件添加功能
+
+参考示例 [examples](./examples)，可通过自己实现 `AddAddon` 方法添加自己实现的插件。
+
+下面列出目前支持的事件节点：
+
+```golang
+type Addon interface {
+	// 一个客户端已经连接到了mitmproxy。请注意，一个连接可能对应多个HTTP请求。
+	ClientConnected(*ClientConn)
+
+	// 一个客户端连接已关闭（由我们或客户端关闭）。
+	ClientDisconnected(*ClientConn)
+
+	// mitmproxy 已连接到服务器。
+	ServerConnected(*ConnContext)
+
+	// 服务器连接已关闭（由我们或服务器关闭）。
+	ServerDisconnected(*ConnContext)
+
+	// 与服务器的TLS握手已成功完成。
+	TlsEstablishedServer(*ConnContext)
+
+	// HTTP请求头已成功读取。此时，请求体为空。
+	Requestheaders(*Flow)
+
+	// 完整的HTTP请求已被读取。
+	Request(*Flow)
+
+	// HTTP响应头已成功读取。此时，响应体为空。
+	Responseheaders(*Flow)
+
+	// 完整的HTTP响应已被读取。
+	Response(*Flow)
+
+	// 流式请求体修改器
+	StreamRequestModifier(*Flow, io.Reader) io.Reader
+
+	// 流式响应体修改器
+	StreamResponseModifier(*Flow, io.Reader) io.Reader
+}
+```
+
+## WEB 界面
+
+你可以通过浏览器访问 http://localhost:9081/ 来使用 WEB 界面。
+
+### 功能点
+
+- 查看 HTTP/HTTPS 请求的详细信息
+- 支持对 JSON 请求/响应进行格式化预览
+- 支持二进制模式查看响应体
+- 支持高级的筛选过滤规则
+- 支持请求断点功能
+
+### 截图示例
+
+![](./assets/web-1.png)
+
+![](./assets/web-2.png)
+
+![](./assets/web-3.png)
+
+## License
+
+[MIT License](./LICENSE)

README_EN.md

@@ -1,84 +0,0 @@
-# go-mitmproxy
-
-[简体中文](./README.md)
-
-[Mitmproxy](https://mitmproxy.org/) implemented with golang. Intercept HTTP & HTTPS requests and responses and modify them.
-
-## Features
-
-- Intercept HTTP & HTTPS requests and responses and modify them on the fly
-- SSL/TLS certificates for interception are generated on the fly
-- Certificates logic compatible with [mitmproxy](https://mitmproxy.org/), saved at `~/.mitmproxy`. If you used mitmproxy before and installed certificates, then you can use this go-mitmproxy directly
-- Addon mechanism, you can add your functions easily, refer to [examples](./examples)
-- Performance advantages
-  - Golang's inherent performance advantages
-  - Forwarding and parsing HTTPS traffic in process memory without inter-process communication such as tcp port or unix socket
-  - Use LRU cache when generating certificates of different domain names to avoid double counting
-- Support `Wireshark` to analyze traffic through the environment variable `SSLKEYLOGFILE`
-- Support streaming when uploading/downloading large files
-- Web interface
-
-## Install
-
-```
-go install github.com/lqqyt2423/go-mitmproxy/cmd/go-mitmproxy@latest
-```
-
-## Usage
-
-### Startup
-
-```
-go-mitmproxy
-```
-
-After startup, the HTTP proxy address defaults to port 9080, and the web interface defaults to port 9081.
-
-After the first startup, the SSL/TLS certificate will be automatically generated at `~/.mitmproxy/mitmproxy-ca-cert.pem`. You can refer to this link to install: [About Certificates](https://docs.mitmproxy.org/stable/concepts-certificates/).
-
-### Help
-
-```
-Usage of go-mitmproxy:
-  -addr string
-    	proxy listen addr (default ":9080")
-  -cert_path string
-    	path of generate cert files
-  -debug int
-    	debug mode: 1 - print debug log, 2 - show debug from
-  -dump string
-    	dump filename
-  -dump_level int
-    	dump level: 0 - header, 1 - header + body
-  -mapper_dir string
-    	mapper files dirpath
-  -ssl_insecure
-    	not verify upstream server SSL/TLS certificates.
-  -version
-    	show version
-  -web_addr string
-    	web interface listen addr (default ":9081")
-```
-
-## Usage as package
-
-Refer to [cmd/go-mitmproxy/main.go](./cmd/go-mitmproxy/main.go), you can add your own addon by call `AddAddon` method.
-
-For more examples, please refer to [examples](./examples)
-
-## Web interface
-
-![](./assets/web-1.png)
-
-![](./assets/web-2.png)
-
-![](./assets/web-3.png)
-
-## TODO
-
-- [ ] Support http2
-- [ ] Support parse websocket
-
-## License
-
-[MIT License](./LICENSE)