DOCSEARCHbyAlgolia
Submit Docs

go-mitmproxy Documentation

repository·main·Indexed 23 days ago

https://github.com/lqqyt2423/go-mitmproxy

A Golang implementation of mitmproxy for man-in-the-middle attacks, monitoring, and tampering with HTTP/HTTPS, WebSocket, and SSE traffic. It features a web interface for traffic inspection, a CLI tool for configuration, and an extensible Addon interface for intercepting lifecycle events such as TLS handshakes and request/response headers. Includes the dummycert tool for generating test certificates and a React-based client for visual traffic monitoring.

Tokens
9.8K
Snippets
18
Records
47
Agent score
80%

What's inside go-mitmproxy

  1. Use scope prefixes in web filter rules

    main

    When filtering flows in the web interface, you can specify a scope before a keyword using the scope:keyword syntax. If no scope is provided, the default scope is url.

    Available scopes:

    • url: Request URL
    • method: HTTP request method (e.g., GET, POST)
    • code: HTTP response status code
    • reqheader: Request headers
    • resheader: Response headers
    • header: Either request or response headers
    • reqbody: Request body
    • resbody: Response body
    • body: Either request or response body
    • all: Any of URL, Method, Header, or Body

  2. Extend go-mitmproxy with custom Addons (Plugins)

    main

    To add custom functionality, implement the Addon interface. You can hook into various lifecycle events such as client connections, HTTP request/response headers, full request/response bodies, and WebSocket/SSE events.

    Key event hooks include:

    • ClientConnected(*ClientConn) / ClientDisconnected(*ClientConn)
    • Requestheaders(*Flow) / Responseheaders(*Flow)
    • Request(*Flow) / Response(*Flow)
    • StreamRequestModifier(*Flow, io.Reader) io.Reader (for streaming request body modification)
    • StreamResponseModifier(*Flow, io.Reader) io.Reader (for streaming response body modification)
    • WebSocketStart(*Flow) / WebSocketMessage(*Flow) / WebSocketEnd(*Flow)
    • SSEStart(*Flow) / SSEMessage(*Flow) / SSEEnd(*Flow)
    • RequestError(*Flow, error) / HTTPConnectError(*Flow, error)
    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

	// WebSocket 连接建立
	WebSocketStart(*Flow)

	// WebSocket 消息接收
	WebSocketMessage(*Flow)

	// WebSocket 连接关闭
	WebSocketEnd(*Flow)

	// SSE 连接建立
	SSEStart(*Flow)

	// SSE 消息接收
	SSEMessage(*Flow)

	// SSE 连接关闭
	SSEEnd(*Flow)

	// HTTP 请求失败
	RequestError(*Flow, error)

	// HTTP CONNECT 请求失败
	HTTPConnectError(*Flow, error)
}

  3. Use the Web Interface for traffic monitoring

    main

    The go-mitmproxy web interface allows you to inspect intercepted traffic visually. Access it at http://localhost:9081/ (or the address specified by -web_addr).

    Key features:

    • View detailed HTTP/HTTPS request and response information.
    • Formatted JSON previews for requests and responses.
    • Binary mode for viewing response bodies.
    • Advanced filtering rules.
    • Request breakpoint functionality.

  5. Filter flows by Request or Response Body

    main

    To search for specific text within the message bodies, use the following scopes:

    • reqbody:keyword: Search in the request body.
    • resbody:keyword: Search in the response body.
    • body:keyword: Search in either the request or response body.

    To search for a string containing spaces, wrap the value in double quotes.

    reqbody:token
resbody:token
body:token
resbody:"hello world"

  6. Run the go-mitmproxy proxy server

    main

    To start the proxy server, run the following command:

    go-mitmproxy

    By default:

    • The HTTP proxy listens on port 9080.
    • The Web interface is available on port 9081.

    Note on HTTPS: On the first run, certificates are automatically generated at ~/.mitmproxy/mitmproxy-ca-cert.pem. You must install this certificate in your client/browser to intercept HTTPS traffic. If you have previously used the Python version of mitmproxy and trusted its root certificate, go-mitmproxy can use it directly.

  7. Filter flows by URL, Method, Code, and Headers

    main

    Use the following syntax to filter specific flow attributes in the web interface:

    • URL: Use url:keyword or just keyword (defaults to URL).
    • Method: Use method:keyword (case-insensitive, e.g., method:get).
    • Status Code: Use code:number (e.g., code:404).
    • Headers: Use header:keyword to search in both request and response headers, or use reqheader: and resheader: for specific directions.
    url:github
method:get
code:404
header:application/json

  8. Use logical operators in filter rules

    main

    You can combine multiple filter criteria using logical operators to create complex queries:

    • or: Matches if either condition is true (e.g., google or baidu).
    • and: Matches if all conditions are true (e.g., method:post and body:hello).
    • not: Excludes flows matching the condition (e.g., not url:github).
    • Parentheses: Use () to group expressions and control operator precedence.
    google or baidu
method:post and body:hello
not url:github
method:get and (url:google or url:baidu) and not resheader:html

  9. Use the Web Interface to inspect traffic

    main

    The Web interface allows you to monitor and interact with intercepted traffic via a browser. Access it at http://localhost:9081/.

    Key Features:

    • View detailed HTTP/HTTPS request and response information.
    • Formatted preview for JSON request/response bodies.
    • Binary mode for viewing response bodies.
    • Advanced filtering rules for searching traffic.
    • Request breakpoint functionality.

  10. Manage the mitmproxy-client development lifecycle

    main

    The mitmproxy-client is a React application bootstrapped with Create React App. You can manage the application using the following yarn scripts:

    • Development: Use yarn start to run the app in development mode. The app will be available at http://localhost:3000. The page reloads automatically on edits and displays lint errors in the console.
    • Testing: Use yarn test to launch the test runner in interactive watch mode.
    • Production Build: Use yarn build to create a production-ready, minified bundle in the build folder. This version is optimized for performance and includes file hashes for cache busting.
    • Custom Configuration (Eject): Use yarn eject if you need full control over the underlying build tools (webpack, Babel, ESLint, etc.). Warning: This is a one-way operation and cannot be undone.
    yarn start
yarn test
yarn build
yarn eject

  11. Manage WebSocket communication in the Web UI

    main

    The web interface communicates with the go-mitmproxy backend via a WebSocket connection. The App component handles connection stability and message queuing.

    Connection Details

    • Endpoint: ws://${host}/echo (where host is localhost:9081 in development or the current document host in production).
    • Binary Type: Set to arraybuffer.
    • Reconnection Logic: If the connection closes unexpectedly, the client attempts to reconnect using an interval sequence: [1, 1, 2, 2, 4, 4, 8, 8, 16, 16, 32, 32] seconds.

    Sending Messages

    Messages are sent using the wsSend method. If the WebSocket is not currently OPEN, messages are queued in a pendingMessages buffer (limited to the last 10 messages) and sent immediately upon reconnection.

  12. Implement Addon lifecycle events

    main

    To extend the proxy's functionality, you implement the Addon interface (implied by usage in proxy/entry.go). The proxy triggers several lifecycle events that your addon can hook into:

    • ClientConnected(connCtx *ConnContext): Called when a new client TCP connection is established.
    • ClientDisconnected(connCtx *ConnContext): Called when the client connection is closed.
    • ServerDisconnected(connCtx *ConnContext): Called when the upstream server connection is closed.
    • Requestheaders(f *Flow): Called during a CONNECT request before interception logic proceeds.
    • Responseheaders(f *Flow): Called after a successful CONNECT establishment (HTTP 200) but before data transfer.
    • HTTPConnectError(f *Flow, err error): Called if an error occurs during the CONNECT handshake.
    • AccessProxyServer(req *http.Request, res http.ResponseWriter): Called when a non-absolute URL is requested directly against the proxy server.