From 831873c9a6e0e51914d09ad8d15918858bf58562 Mon Sep 17 00:00:00 2001 From: lqqyt2423 <974923609@qq.com> Date: Tue, 14 Feb 2023 15:51:12 +0800 Subject: [PATCH] readme --- README.md | 154 +++++++++++++++++++++++++++++++++++------------ README_CN.md | 164 +++++++++++++++++++++++++++++++++++++++++++++++++++ README_EN.md | 84 -------------------------- 3 files changed, 281 insertions(+), 121 deletions(-) create mode 100644 README_CN.md delete mode 100644 README_EN.md diff --git a/README.md b/README.md index 8bc531e..0f7580e 100644 --- a/README.md +++ b/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` 可以直接使用 -- 支持插件机制，很方便扩展自己需要的功能，可参考 [examples](./examples) -- 性能优势 - - Golang 天生的性能优势 - - 在进程内存中转发解析 HTTPS 流量，不需通过 tcp 端口 或 unix socket 等进程间通信 - - 生成不同域名证书时使用 LRU 缓存，避免重复计算 -- 通过环境变量 `SSLKEYLOGFILE` 支持 `Wireshark` 解析分析流量 -- 上传/下载大文件时支持流式传输 -- Web 界面 +## Unsupported features -## 安装 +- 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 - dump filename - -dump_level int - dump level: 0 - header, 1 - header + body - -mapper_dir string - mapper files dirpath + -f string + Read configuration from file by passing in the file path of a JSON configuration file. + -ignore_hosts value + a list of ignore hosts -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) diff --git a/README_CN.md b/README_CN.md new file mode 100644 index 0000000..06b1142 --- /dev/null +++ b/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) diff --git a/README_EN.md b/README_EN.md deleted file mode 100644 index 0178121..0000000 --- a/README_EN.md +++ /dev/null @@ -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)