Grasscutters/mitmproxy
3
0
Fork 0
mirror of https://github.com/Grasscutters/mitmproxy.git synced 2024-11-23 00:01:36 +00:00
Code Issues Projects Releases Wiki Activity

improve transparent mode docs

Browse Source
This commit is contained in:
Maximilian Hils 2018-03-20 16:00:23 +01:00
parent 252684e14e
commit 9748487939
1 changed files with 203 additions and 208 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

411
docs/src/content/howto-transparent.md
View File

@ -27,7 +27,209 @@ At the moment, mitmproxy supports transparent proxying on OSX Lion and above,
and all current flavors of Linux. and all current flavors of Linux.
## Linux fully transparent mode ## Linux
On Linux, mitmproxy integrates with the iptables redirection mechanism to
achieve transparent mode.
### 1. Enable IP forwarding.
{{< highlight bash >}}
sysctl -w net.ipv4.ip_forward=1
sysctl -w net.ipv6.conf.all.forwarding=1
{{< / highlight >}}
This makes sure that your machine forwards packets instead of rejecting them.
If you want to persist this across reboots, you need to adjust your `/etc/sysctl.conf` or
a newly created `/etc/sysctl.d/mitmproxy.conf` (see [here](https://superuser.com/a/625852)).
### 2. Disable ICMP redirects.
{{< highlight bash >}}
sysctl -w net.ipv4.conf.all.send_redirects=0
{{< / highlight >}}
If your test device is on the same physical network, your machine shouldn't inform the device that
there's a shorter route available by skipping the proxy.
If you want to persist this across reboots, see above.
### 3. Create an iptables ruleset that redirects the desired traffic to mitmproxy.
Details will differ according to your setup, but the ruleset should look
something like this:
{{< highlight bash >}}
iptables -t nat -A PREROUTING -i eth0 -p tcp --dport 80 -j REDIRECT --to-port 8080
iptables -t nat -A PREROUTING -i eth0 -p tcp --dport 443 -j REDIRECT --to-port 8080
ip6tables -t nat -A PREROUTING -i eth0 -p tcp --dport 80 -j REDIRECT --to-port 8080
ip6tables -t nat -A PREROUTING -i eth0 -p tcp --dport 443 -j REDIRECT --to-port 8080
{{< / highlight >}}
If you want to persist this across reboots, you can use the `iptables-persistent` package (see
[here](http://www.microhowto.info/howto/make_the_configuration_of_iptables_persistent_on_debian.html)).
### 4. Fire up mitmproxy.
You probably want a command like this:
{{< highlight bash >}}
mitmproxy --mode transparent --showhost
{{< / highlight >}}
The `--mode transparent` option turns on transparent mode, and the `--showhost` argument tells
mitmproxy to use the value of the Host header for URL display.
### 5. Finally, configure your test device.
Set the test device up to use the host on which mitmproxy is running as the default gateway and
[install the mitmproxy certificate authority on the test device]({{< relref "concepts-certificates" >}}).
## OpenBSD
### 1. Enable IP forwarding.
{{< highlight bash >}}
sudo sysctl -w net.inet.ip.forwarding=1
{{< / highlight >}}
### 2. Place the following two lines in **/etc/pf.conf**.
{{< highlight none >}}
mitm_if = "re2"
pass in quick proto tcp from $mitm_if to port { 80, 443 } divert-to 127.0.0.1 port 8080
{{< / highlight >}}
These rules tell pf to divert all traffic from `$mitm_if` destined for port 80
or 443 to the local mitmproxy instance running on port 8080. You should replace
`$mitm_if` value with the interface on which your test device will appear.
### 3. Configure pf with the rules.
{{< highlight bash >}}
doas pfctl -f /etc/pf.conf
{{< / highlight >}}
### 4. And now enable it.
{{< highlight bash >}}
doas pfctl -e
{{< / highlight >}}
### 5. Fire up mitmproxy.
You probably want a command like this:
{{< highlight bash >}}
mitmproxy --mode transparent --showhost
{{< / highlight >}}
The `--mode transparent` option turns on transparent mode, and the `--showhost` argument tells
mitmproxy to use the value of the Host header for URL display.
### 6. Finally, configure your test device.
Set the test device up to use the host on which mitmproxy is running as the default gateway and
[install the mitmproxy certificate authority on the test device]({{< relref "concepts-certificates" >}}).
{{% note %}}
Note that the **divert-to** rules in the pf.conf given above only apply
to inbound traffic. **This means that they will NOT redirect traffic
coming from the box running pf itself.** We can't distinguish between an
outbound connection from a non-mitmproxy app, and an outbound connection
from mitmproxy itself - if you want to intercept your traffic, you
should use an external host to run mitmproxy. Nonetheless, pf is
flexible to cater for a range of creative possibilities, like
intercepting traffic emanating from VMs. See the **pf.conf** man page
for more.
{{% /note %}}
## macOS
OSX Lion integrated the [pf](https://en.wikipedia.org/wiki/PF_(firewall))
packet filter from the OpenBSD project, which mitmproxy uses to implement
transparent mode on OSX. Note that this means we don't support transparent mode
for earlier versions of OSX.
### 1. Enable IP forwarding.
{{< highlight bash >}}
sudo sysctl -w net.inet.ip.forwarding=1
{{< / highlight >}}
### 2. Place the following two lines in a file called, say, **pf.conf**.
{{< highlight none >}}
rdr on en0 inet proto tcp to any port {80, 443} -> 127.0.0.1 port 8080
{{< / highlight >}}
These rules tell pf to redirect all traffic destined for port 80 or 443
to the local mitmproxy instance running on port 8080. You should replace
`en2` with the interface on which your test device will appear.
### 3. Configure pf with the rules.
{{< highlight bash >}}
sudo pfctl -f pf.conf
{{< / highlight >}}
### 4. And now enable it.
{{< highlight bash >}}
sudo pfctl -e
{{< / highlight >}}
### 5. Configure sudoers to allow mitmproxy to access pfctl.
Edit the file **/etc/sudoers** on your system as root. Add the following line to
the end of the file:
{{< highlight none >}}
ALL ALL=NOPASSWD: /sbin/pfctl -s state
{{< / highlight >}}
Note that this allows any user on the system to run the command `/sbin/pfctl -s
state` as root without a password. This only allows inspection of the state
table, so should not be an undue security risk. If you're special feel free to
tighten the restriction up to the user running mitmproxy.
### 6. Fire up mitmproxy.
You probably want a command like this:
{{< highlight bash >}}
mitmproxy --mode transparent --showhost
{{< / highlight >}}
The `--mode transparent` flag turns on transparent mode, and the `--showhost` argument tells
mitmproxy to use the value of the Host header for URL display.
### 7. Finally, configure your test device.
Set the test device up to use the host on which mitmproxy is running as the default gateway and
[install the mitmproxy certificate authority on the test device]({{< relref "concepts-certificates" >}}).
{{% note %}}
Note that the **rdr** rules in the pf.conf given above only apply to
inbound traffic. **This means that they will NOT redirect traffic coming
from the box running pf itself.** We can't distinguish between an
outbound connection from a non-mitmproxy app, and an outbound connection
from mitmproxy itself - if you want to intercept your OSX traffic, you
should use an external host to run mitmproxy. Nonetheless, pf is
flexible to cater for a range of creative possibilities, like
intercepting traffic emanating from VMs. See the **pf.conf** man page
for more.
{{% /note %}}
## "Full" transparent mode on Linux
By default mitmproxy will use its own local IP address for its server-side By default mitmproxy will use its own local IP address for its server-side
connections. In case this isn't desired, the --spoof-source-address argument can connections. In case this isn't desired, the --spoof-source-address argument can
@ -60,210 +262,3 @@ sudo chown root:root mitmproxy_shim
sudo chmod u+s mitmproxy_shim sudo chmod u+s mitmproxy_shim
./mitmproxy_shim $(which mitmproxy) --mode transparent --set spoof-source-address ./mitmproxy_shim $(which mitmproxy) --mode transparent --set spoof-source-address
{{< / highlight >}} {{< / highlight >}}
## Linux
On Linux, mitmproxy integrates with the iptables redirection mechanism to
achieve transparent mode.
### 1. [Install the mitmproxy certificate on the test device]({{< relref "concepts-certificates" >}})
### 2. Enable IP forwarding:
{{< highlight bash >}}
sysctl -w net.ipv4.ip_forward=1
sysctl -w net.ipv6.conf.all.forwarding=1
{{< / highlight >}}
You may also want to consider enabling this permanently in `/etc/sysctl.conf` or
newly created `/etc/sysctl.d/mitmproxy.conf`, see
[here](https://superuser.com/a/625852).
### 3. If your target machine is on the same physical network and you configured it to use a custom gateway, disable ICMP redirects:
{{< highlight bash >}}
sysctl -w net.ipv4.conf.all.send_redirects=0
{{< / highlight >}}
You may also want to consider enabling this permanently in `/etc/sysctl.conf` or
a newly created `/etc/sysctl.d/mitmproxy.conf`, see
[here](https://superuser.com/a/625852).
### 4. Create an iptables ruleset that redirects the desired traffic to the mitmproxy port
Details will differ according to your setup, but the ruleset should look
something like this:
{{< highlight bash >}}
iptables -t nat -A PREROUTING -i eth0 -p tcp --dport 80 -j REDIRECT --to-port 8080
iptables -t nat -A PREROUTING -i eth0 -p tcp --dport 443 -j REDIRECT --to-port 8080
ip6tables -t nat -A PREROUTING -i eth0 -p tcp --dport 80 -j REDIRECT --to-port 8080
ip6tables -t nat -A PREROUTING -i eth0 -p tcp --dport 443 -j REDIRECT --to-port 8080
{{< / highlight >}}
   You may also want to consider enabling this permanently with the
`iptables-persistent` package, see
[here](http://www.microhowto.info/howto/make_the_configuration_of_iptables_persistent_on_debian.html).
### 5. Fire up mitmproxy
You probably want a command like this:
{{< highlight bash >}}
mitmproxy --mode transparent --showhost
{{< / highlight >}}
The `--mode transparent` option turns on transparent mode, and the `--showhost` argument tells
mitmproxy to use the value of the Host header for URL display.
### 6. Finally, configure your test device
Set the test device up to use the host on which mitmproxy is running as the
default gateway. For a detailed walkthrough, have a look at the [tutorial for
transparently proxying VMs]({{< relref "howto-transparent-vms" >}}).
## OpenBSD
### 1 [Install the mitmproxy certificate on the test device]({{< relref "concepts-certificates" >}})
### 2. Enable IP forwarding
{{< highlight bash >}}
sudo sysctl -w net.inet.ip.forwarding=1
{{< / highlight >}}
### 3. Place the following two lines in **/etc/pf.conf**
{{< highlight none >}}
mitm_if = "re2"
pass in quick proto tcp from $mitm_if to port { 80, 443 } divert-to 127.0.0.1 port 8080
{{< / highlight >}}
These rules tell pf to divert all traffic from `$mitm_if` destined for port 80
or 443 to the local mitmproxy instance running on port 8080. You should replace
`$mitm_if` value with the interface on which your test device will appear.
### 4. Enable the pf ruleset and enable it
{{< highlight bash >}}
doas pfctl -f /etc/pf.conf
{{< / highlight >}}
And now enable it:
{{< highlight bash >}}
doas pfctl -e
{{< / highlight >}}
### 5. Fire up mitmproxy
You probably want a command like this:
{{< highlight bash >}}
mitmproxy --mode transparent --showhost
{{< / highlight >}}
The `--mode transparent` option turns on transparent mode, and the `--showhost` argument tells
mitmproxy to use the value of the Host header for URL display.
### 6. Finally, configure your test device
Set the test device up to use the host on which mitmproxy is running as the
default gateway.
{{% note %}}
Note that the **divert-to** rules in the pf.conf given above only apply
to inbound traffic. **This means that they will NOT redirect traffic
coming from the box running pf itself.** We can't distinguish between an
outbound connection from a non-mitmproxy app, and an outbound connection
from mitmproxy itself - if you want to intercept your traffic, you
should use an external host to run mitmproxy. Nonetheless, pf is
flexible to cater for a range of creative possibilities, like
intercepting traffic emanating from VMs. See the **pf.conf** man page
for more.
{{% /note %}}
## macOS
OSX Lion integrated the [pf](https://en.wikipedia.org/wiki/PF_(firewall))
packet filter from the OpenBSD project, which mitmproxy uses to implement
transparent mode on OSX. Note that this means we don't support transparent mode
for earlier versions of OSX.
### 1. [Install the mitmproxy certificate on the test device]({{< relref "concepts-certificates" >}})
### 2. Enable IP forwarding
{{< highlight bash >}}
sudo sysctl -w net.inet.ip.forwarding=1
{{< / highlight >}}
### 3. Place the following two lines in a file called, say, **pf.conf**
{{< highlight none >}}
rdr on en0 inet proto tcp to any port {80, 443} -> 127.0.0.1 port 8080
{{< / highlight >}}
These rules tell pf to redirect all traffic destined for port 80 or 443
to the local mitmproxy instance running on port 8080. You should replace
`en2` with the interface on which your test device will appear.
### 4. Configure pf with the rules
{{< highlight bash >}}
sudo pfctl -f pf.conf
{{< / highlight >}}
### 5. And now enable it
{{< highlight bash >}}
sudo pfctl -e
{{< / highlight >}}
### 6. Configure sudoers to allow mitmproxy to access pfctl
Edit the file **/etc/sudoers** on your system as root. Add the following line to
the end of the file:
{{< highlight none >}}
ALL ALL=NOPASSWD: /sbin/pfctl -s state
{{< / highlight >}}
Note that this allows any user on the system to run the command `/sbin/pfctl -s
state` as root without a password. This only allows inspection of the state
table, so should not be an undue security risk. If you're special feel free to
tighten the restriction up to the user running mitmproxy.
### 7. Fire up mitmproxy
You probably want a command like this:
{{< highlight bash >}}
mitmproxy --mode transparent --showhost
{{< / highlight >}}
The `--mode transparent` flag turns on transparent mode, and the `--showhost` argument tells
mitmproxy to use the value of the Host header for URL display.
### 6. Finally, configure your test device
Set the test device up to use the host on which mitmproxy is running as the
default gateway.
{{% note %}}
Note that the **rdr** rules in the pf.conf given above only apply to
inbound traffic. **This means that they will NOT redirect traffic coming
from the box running pf itself.** We can't distinguish between an
outbound connection from a non-mitmproxy app, and an outbound connection
from mitmproxy itself - if you want to intercept your OSX traffic, you
should use an external host to run mitmproxy. Nonetheless, pf is
flexible to cater for a range of creative possibilities, like
intercepting traffic emanating from VMs. See the **pf.conf** man page
for more.
{{% /note %}}