New Proxy Modes

[mhils]

Current Status

mitmproxy currently has documentation for the following proxy modes:

• regular (acting as an HTTP(S)/1 proxy)
• socks5 (acting as a SOCKSv5 proxy)
• reverse:... (acting as a TCP/HTTP reverse proxy)
• upstream:... (acting as an HTTP(S) proxy)
• transparent

All those modes are TCP-based and do "sub-protocol sniffing", i.e. our regular HTTP proxy is able to detect non-HTTP traffic and proxy generic TCP connections.

New Modes! 🥳

We are in the process of getting a whole bunch of new operating modes:

• transparent proxying for UDP/DNS/DTLS/QUIC
• reverse proxying for UDP/DNS/DTLS/QUIC
• DNS server
• QUIC/HTTP/3 proxy server
• OS proxying (transparent mode + automatically redirect traffic from current device)
• WireGuard (transparent mode via WireGuard endpoint)

Now the question is what's the best way to expose that. Do we have a transparent mode and a separate udp:transparent (or transparent:udp) mode, or does transparent start listeners for TCP and UDP? Likewise, is is quic:reverse:example.com, or reverse:quic://example.com ?

Here are some first thoughts:

• For reverse proxies, we could request from users to specify the protocol, e.g. reverse:udp://example.com or udp:reverse:example.com. It feels like the former syntax integrates a bit nicer with the existing specs.
• For transparent proxies, there are some cases where we need to do protocol sniffing (e.g. OS proxying). I think it makes some sense to always do that for transparent mode. This would mean we don't want dns:transparent and quic:transparent, but maybe just one transparent mode that works for both TCP and UDP? (optionally with transparent:tcp-only to only spawn a TCP listener)
• What do we do about DNS? A combination of dns-server, reverse:dns://example.com, and transparent? (seems fine to me)
• One potential issue with reverse:https://example.com is that it leaves the transport protocol unspecified. Do we then spawn both TCP (h1, h2) and UDP sockets (h3)? Or do expect users to add an additional quic:// spec if they want UDP/QUIC as well?
• We probably don't want to do any super hard compatibility breaks. It would be nice if mitmproxy --mode reverse:... continues to work. The newer modes (dns, dtls) are new enough to be broken.

@meitinger @Prinzhorn @decathorpe @kckeiks and @mitmproxy/devs, let me know what you think!

[meitinger]

Personally, I'd be cautious about unifying reverse over multiple protocols, at least with how the current code handles modes. ReverseMode and ReverseInstance will then need to know about other protocols that support reverse mode. Also, if one protocol needs additional parameters, ReverseMode must be updated to include these arguments as fields and parse them. So new protocols can't be added as unintrusively.
Case in point: With the current QUIC implementation, I actually planned to support quic:reverse:h2://example.com in order to listen for h3 but connect to example.com with h2. This requires a version field. reverse:quic://example.com can't reflect that.

Unifying transparent, however, makes sense to me, as it ideally should monitor everything, and infer parameters from the connection. Maybe we could add two methods to ProxyMode (or another class that uses a similar registration method), one for TCP and one for UDP sniffing, that can be implemented by subclasses. The TCP one gets the data provided so far, similar to what NextLayer already does, the UDP one gets the received datagram. TransparentInstance would then handle all the capture code and query every registered ProxyMode (or instances of that other class) whenever a new connection is made.

[mhils]

Personally, I'd be cautious about unifying reverse over multiple protocols, at least with how the current code handles modes.

Fully agree that it's less than ideal from an implementation perspective. Then again we should focus on what is most intuitive for users.

Also, if one protocol needs additional parameters, ReverseMode must be updated to include these arguments as fields and parse them. So new protocols can't be added as unintrusively.

Just to spin the experiment further, you could represent additional arguments like this: reverse:https://example.com?keep_host_header=true. There's a bit of precedent for such constructs in SQL connection URIs for example.

quic:reverse:h2://example.com

Playing devil's advocate here: If reverse:https://example.com spawns both TCP and UDP listeners, this would also "just work". This dual protocol problem only affects HTTP I think (then again HTTP is what we should care about most).

Unifying transparent, however, makes sense to me, as it ideally should monitor everything, and infer parameters from the connection. Maybe we could add two methods to ProxyMode (or another class that uses a similar registration method), one for TCP and one for UDP sniffing, that can be implemented by subclasses.

+1 overall! I'd be tempted to just keep all the proto sniffing in NextLayer and not delegate to modes, but that's an implementation detail. If you write a custom mode that is not part of mitmproxy itself, you can just hook into next_layer yourself. "I have implemented my own mode/protocol which I don't want to contribute to the project" is an edge case user we should rank very low in priority.

[meitinger]

Personally, I'd be cautious about unifying reverse over multiple protocols, at least with how the current code handles modes.

Fully agree that it's less than ideal from an implementation perspective. Then again we should focus on what is most intuitive for users.

That's a good point... In that case, how about having a registration mechanism for mode types, so basically what we do now, but for each of the four modes? Ideally the registration would say what scheme is supported. Thus h1-h3 could all register for the https scheme in reverse mode.

Just to spin the experiment further, you could represent additional arguments like this: reverse:https://example.com?keep_host_header=true. There's a bit of precedent for such constructs in SQL connection URIs for example.

I'm all for that. In that case, we could give ProxyMode an options field, that contains all global options with ?... overrides.

Playing devil's advocate here: If reverse:https://example.com spawns both TCP and UDP listeners, this would also "just work". This dual protocol problem only affects HTTP I think (then again HTTP is what we should care about most).

Agreed, but in that case I'd suggest not doing the @port anymore, but rather have reverse:https://example.com?listen_port=x and also reverse:https://example.com?tcp_listen_port=x&quic_listen_port=y. (Or whatever the name of add_option is.)

+1 overall! I'd be tempted to just keep all the proto sniffing in NextLayer and not delegate to modes

Even better, I'll keep that in mind when doing QUIC, so that NextLayer will always be involved.

[mhils]

Agreed, but in that case I'd suggest not doing the @port anymore, but rather have reverse:https://example.com?listen_port=x and also reverse:https://example.com?tcp_listen_port=x&quic_listen_port=y. (Or whatever the name of add_option is.)

👍 from my end.

[Prinzhorn]

Just to spin the experiment further, you could represent additional arguments like this: reverse:https://example.com?keep_host_header=true. There's a bit of precedent for such constructs in SQL connection URIs for example.

Loving it, see my "Uh oh" here: #4656 (comment)
I'm all for embracing the URL format and duplicate query params (for sequence options) are also no problem.

But at what point do we go full circle and have a ?mode=quic or whatever parameter instead of having it as part of the mode spec? What I'm saying is that basically all options could be URL parameters (and mode is basically just a way to specify sets of options), but I understand that the listen_host just looks nicer as an actual host. Can someone compile a list of examples URLs for all types of use-cases so we can see if that actually works and looks usable?

[Prinzhorn]

FWIW I liked @port, because that's by far the option I (arguably most people) need to touch the most and it's easier to type 😄

[kckeiks]

One potential issue with reverse:https://example.com is that it leaves the transport protocol unspecified. Do we then spawn both TCP (h1, h2) and UDP sockets (h3)? Or do expect users to add an additional quic:// spec if they want UDP/QUIC as well?

I think it would be better to be explicit and use the form proto:reverse://example.com.

Have you considered allowing users to specify their reverse proxy configuration via a config file? Given the features that have been added (and may be added in the future), it might get harder to capture the different available configurations through the command line. This would also help avoid breaking mitmproxy --mode reverse:... so if a user wants the fancy features and configurations, they would have to use a config file.

This would mean we don't want dns:transparent and quic:transparent, but maybe just one transparent mode that works for both TCP and UDP? (optionally with transparent:tcp-only to only spawn a TCP listener)

+1

[mhils]

I think it would be better to be explicit and use the form proto:reverse://example.com.

But what is more explicit in proto:reverse://example.com compared to reverse:proto://example.com? I think I don't get our point here. 🙃

Have you considered allowing users to specify their reverse proxy configuration via a config file?

For the record you can already specify modes in config.yaml, but I think you are proposing something more explicit, maybe like this?

servers:
  - protocol: http
    destination: http://example.com 
    listen_port: 80
  - protocol: dns
    listen_port: 53

That looks great to me, but I'd love to keep/add some way of configuring that via the CLI. I have had the pleasure to deal with this kind of construct in OpenSSL repeatedly.... first writing out a config file before invoking the executable is just pain. One way around this would be to add something that directly maps to this (mitmdump --server protocol=http&destination=http://example.com&listen_port=53) while keeping --mode as is. Not sure how much of a fan I am of this. Does anyone else have opinions?

[kckeiks]

But what is more explicit in proto:reverse://example.com compared to reverse:proto://example.com? I think I don't get our point here. upside_down_face

I meant proto:reverse://example.com (or reverse:proto://example.com) is more explicit because it includes the transport protocol.

servers:
  - protocol: http
    destination: http://example.com 
    listen_port: 80
  - protocol: dns
    listen_port: 53

Yes, something like that is what I had in mind.

[meitinger]

After reviewing NextLayer and the decision process, how about doing the following:

• don't implement either a quic or dtls mode
• support UdpMode, which in turn parses RegularMode, UpstreamMode etc., i.e. udp:regular:https://example.com
• in NextLayer, use client.transport_protocol to make similar decisions for TCP and UDP, e.g. in TCP we check for TLS magic, in UDP we check for DTLS, or if a scheme is set, we enforce that scheme. (so udp:regular:dtls://example.com would enforce DTLS)
• in DTLS and QUIC, don't use UdpLayer right away, but also NextLayer as child_layer

Once the UDP implementation of QUIC/H3/DTLS is tried and tested, we can drop the udp prefix, and RegularMode, UpstreamMode etc. spawn TCP and UDP listeners themselves.

[mhils]

I think a table like this would be a great addition for our docs once done! :)

Intuitively I would have said the following:

http/https: fully agree
TLS: this is explicitly not HTTP (otherwise you can use https://), so I think it would make sense to accept raw TCP or raw TCP-over-TLS on the client side and always do raw TCP-over-TLS on the server side
TCP: Same as TLS, we just do raw TCP on the server side.
UDP/DTLS: Like TCP/TLS just with UDP instead of TCP.

I haven't fully thought this through and don't want to die on this hill. Either is fine with me, feel free to make a judgement call. :)

[meitinger]

Sounds fine to me too, the only thing that bugs me is the inconsistency with http/https, i.e. if we treat tcp/tls/udp/dtls as an upper bound client-side, and proto server-side, shouldn't http/https behave the same? In that case, https and http would specify the exact protocol server-side, but I guess we could make an exception for clients and accept https for http as well?

[mhils]

I'm not understanding the last point. Can you rephrase?

[meitinger]

Sorry for not being clear, it's also quite likely that I misunderstood your TCP suggestion at first.
To clear things up, allow me to put your suggestion with an altered http row into a table again (I omit equivalent UDP stuff for brevity)

proto	result
tcp	always use raw tcp with server (just TcpLayer), clients can use tls, but no further protocol detection
tls	always use tls with TcpLayer on top with the server, clients can just use tcp, but no further protocol detection than tls
http	always use http with server (no https), clients can use http, https, quic+h3
https	always use https with server, clients can use http, https, quic+h3
quic	always use quic with server, clients also have to use quic 1

Footnotes

1. In theory we could also support a tls <-> quic bridge, where one quic stream is one tls connection. ↩

[mhils]

Yes, that describes it well.¹

Footnotes

1. For the record, I did not propose to support a tls <-> quic bridge. Fun idea, but out of scope. 😅 ↩

[meiraxx]

Hi pros! I'm really interested in what the status is right now for QUIC/HTTP3 support.

Is there like an experimental code implementation somewhere on the project (e.g. random branch)?

[mhils]

QUIC/HTTP3 support has been merged and is on the main branch. We still need to work on docs.