From 82a26e5bc07d796c9c49391c8d796289a6799c41 Mon Sep 17 00:00:00 2001 From: awokd <34515595+awokd@users.noreply.github.com> Date: Thu, 22 Feb 2018 12:38:21 +0000 Subject: [PATCH 1/6] line breaks, misc grammar --- configuration/http-filtering-proxy.md | 178 +++++++++----------------- 1 file changed, 64 insertions(+), 114 deletions(-) diff --git a/configuration/http-filtering-proxy.md b/configuration/http-filtering-proxy.md index 4b0f2e88..e408a69d 100644 --- a/configuration/http-filtering-proxy.md +++ b/configuration/http-filtering-proxy.md @@ -10,160 +10,115 @@ How to run an HTTP filtering proxy in a FirewallVM Introduction ------------ -By default Qubes uses a special firewall VM that sits between the -networking VM and each AppVM. This VM controls the traffic for AppVMs -and can be used to restrict what AppVMs can send or receive. The -traffic rules can be setup using filtering rules GUI in Qubes VM -manager. The manager translates user-defined setup into iptables rules -for the kernel of firewall VM. +By default Qubes uses a special firewall VM that sits between the networking VM and each AppVM. +This VM controls the traffic for AppVMs and can be used to restrict what AppVMs can send or receive. +The traffic rules can be setup using the filtering rules GUI in Qubes VM manager. +The manager translates user-defined setup into iptables rules for the firewall VM's kernel. -The primary goal of the filtering rule setup in firewall VM is to -allow for the user to protect either from own mistakes (like accessing -an arbitrary website from a browser running in a banking VM) or from -mistakes of websites (like a banking website that loads JS code from a -social network operator when the user logs in into the bank). +The primary goal of the filtering rule setup in the firewall VM is to allow for the user to protect either from his own mistakes (like accessing an arbitrary website from a browser running in a banking VM) or from the mistakes of websites (like a banking website that loads JS code from a social network operator when the user logs into the bank). -As the rules in the firewall are IP-based, it has drawbacks. First the -rules cannot be used if one has to use a HTTP proxy to connect for -websites (a common setup on corporate networks). Second the Qubes -resolves DNS names from the firewall rules when the AppVM loads. This -prevents websites that use DNS-based load balancers from working -unless the user reloads the firewall rules (which re-resolve the DNS -names) whenever the balancer transfer her session to another IP. Third -the initial setup of the rules is complicated as the firewall drops -the connection silently. As a workaround one can use browser's network -console to see what is blocked, but this is time-consuming and one can -trivially miss some important cases like including in the firewall -white-list sites for OCSP SSL certificate verification. +As the rules in the firewall are IP-based, it has drawbacks. +First, the rules cannot be used if one has to use an HTTP proxy to connect to websites (a common setup on corporate networks). +Second, Qubes resolves DNS names from the firewall rules when the AppVM loads. +This prevents websites that use DNS-based load balancers from working unless the user reloads the firewall rules (which re-resolve the DNS names) whenever the balancer transfers her session to another IP. +Third, the initial setup of the rules is complicated as the firewall drops the connection silently. +As a workaround, one can use a browser's network console to see what is blocked, but this is time-consuming and one can easily miss some important cases like including sites for OCSP SSL certificate verification in the firewall white-list. -These drawbacks can be mitigated if one replaces iptable-based rules -with a filtering HTTP proxy. The following describes how to setup -tinyproxy-based proxy in the firewall VM to archive such filtering. +These drawbacks can be mitigated if one replaces iptable-based rules with a filtering HTTP proxy. +The following describes how to setup a tinyproxy-based proxy in the firewall VM to achieve such filtering. Warning ------- -Running a HTTP proxy in your firewall VM increases the attack surface -against that VM from a compromised AppVM. tinyproxy has a relatively -simple code and a reasonable track record to allow to certain level of -trust. But one cannot exclude bugs especially in the case of a hostile -proxy clients as this is less tested scenario. So it is not advisable -to use the proxy in a shared firewall VM against untrusted AppVM to -black-list some unwanted connection like advertisement sites. +Running an HTTP proxy in your firewall VM increases the attack surface against that VM from a compromised AppVM. +Tinyproxy has relatively simple code and a reasonable track record to allow to certain level of trust, but one cannot exclude bugs especially in the case of a hostile proxy clients as this is a less tested scenario. +So it is not advisable to use the proxy in a shared firewall VM against untrusted AppVM to black-list some unwanted connections such as advertisement sites. -Less problematic setup is to white-list possible connections for -several trusted and semi-trusted AppVMs within one firewall VM. Still -for maximum safety one should consider running a separated firewall VM -per each important AppVMs and run the proxy there. +A less problematic setup is to white-list possible connections for several trusted and semi-trusted AppVMs within one firewall VM. +Still, for maximum safety one should consider running a separate firewall VM / proxy per each important AppVMs. -As a counterweight to this warning it is important to point out that -HTTP proxy decreases attack surface against AppVM. For example, with a -proxy the AppVM does not need DNS connections so a bug in the kernel -or in the browser in that area would not affect the AppVM. Also -browsers typically avoid many latest and greatest HTTP features when -connection through proxies minimizing exposure of new and unproven -networking code. +As a counterweight to this warning it is important to point out that an HTTP proxy decreases the attack surface of an AppVM. +For example, with a proxy, the AppVM does not need to make direct DNS connections so a bug in the kernel or in the browser in that area would not affect the AppVM. +Also, browsers typically avoid many of the latest and greatest HTTP features when connecting through proxies, minimizing exposure of new and unproven networking code. Setup ----- -1. Copy this [archive] with the proxy control script, default - tinyproxy config and a sample firewall filtering file into the - firewall VM and unpack it in `/rw/config` folder there as root: +1. Copy this [archive] with the proxy control script, default tinyproxy config and a sample firewall filtering file into the firewall VM and unpack it in `/rw/config` folder there as root: cd /rw/config sudo tar xzf .../proxy.tar.xz -2. If necessary adjust `/rw/config/tinyproxy/config` according to the - man page for `tinyproxy.conf`. The included config file refuses the - connection unless the host is white-listed in the filtering file, so - this can be altered if one wants rather to black-list connection. One - may also specify upstream proxies there. The file is a template file - and the control script will replace `{name}` constructs in the file with - actual parameters. In general lines with `{}` should be preserved as is. +2. If necessary, adjust `/rw/config/tinyproxy/config` according to the man page for `tinyproxy.conf`. + The included config file refuses the connection unless the host is white-listed in the filtering file, so this can be altered if one prefers to black-list connections. + One may also specify upstream proxies there. + The file is a template file and the control script will replace `{name}` constructs in the file with actual parameters. + In general, lines with `{}` should be preserved as is. -3. For each AppVM that one wants to run through the proxy create an - the corresponding filtering file in the `/rw/config/tinyproxy` - directory. With the default config the filtering file should contain - regular expressions to match white-listed hosts with one regular - expression per line, see the man page for tinyproxy.conf for details. +3. For each AppVM that one wants to run through the proxy, create a corresponding filtering file in the `/rw/config/tinyproxy` directory. + With the default config, the filtering file should contain regular expressions to match white-listed hosts with one regular expression per line. + See the man page for tinyproxy.conf for details. The file should be named: name.ip-address-of-app-vm - The name part before the dot can be arbitrary. For convenience one can - use AppVM name here, but this is not required. It is important to get - ip address part right as this is what the control script uses to - determine for which AppVM to apply the proxy rules. One can check the - IP address of AppVM in Qubes VM manager in the VM settings dialog, see - the Networking session under the Basic tab. + The name part before the dot is arbitrary. + For convenience, one can use an AppVM name here, but this is not required. + It is important to get the ip address part right as this is what the control script uses to determine on which AppVM it will apply the proxy rules. + One can check the IP address of AppVM in Qubes VM manager in the VM settings dialog; see the Networking session under the Basic tab. - The attached archive includes `tinyproxy/social.10.137.2.13` file with a - rules for a AppVM allowing connection to google, facebook, linkedin, - livejournal, youtube and few other other sites. One can use it as an - example after changing the the IP address accordingly. + The attached archive includes a `tinyproxy/social.10.137.2.13` file with rules for an AppVM allowing connections to Google, Facebook, Linkedin, Livejournal, Youtube, and few other other sites. + One can use it as an example after changing the IP addresses accordingly. - When editing the rules remember to include `$` at the end of the host - name and to prefix each dot in the host name with the backslash. This - way the pattern matches the whole host and not just some prefix and - the dot is not interpreted as an instruction to match an arbitrary - character according to regular expression syntax. + When editing the rules, remember to include a `$` at the end of the host name, and to prefix each dot in the host name with a backslash (like `\.`). + This way, the pattern matches the whole host and not just a prefix, and the dot is not interpreted as an instruction to match an arbitrary character according to regular expression syntax. -4. Check that `proxyctl.py` script can properly recognize the rule - files. For that run: +4. Check that the `proxyctl.py` script can properly recognize the rule files. + For that, run: sudo /rw/config/tinyproxy/proxyctl.py show - For each rule file it should print the name, ip address, network - interface of the running AppVM if AppVM runs and the id of the - tinyproxy process that proxies that AppVM. The first time each pid - should be `--`. + For each rule file it should print the name, ip address, and network interface of the running AppVMs. + It will also display the id of the tinyproxy process that proxies that AppVM. + The first time, each pid should be `--`. -5. Now run some AppVM with proxy and then run: +5. Now run some AppVM with a proxy, and then run: sudo /rw/config/tinyproxy/proxyctl.py update - The update command starts proxy processes and adjusts the iptable - rules to allow for proxy traffic for each running AppVM from the - filtering files list. For each stopped AppVM the proxy is killed. + The update command starts proxy processes and adjusts the iptable rules to allow for proxy traffic for each running AppVM from the filtering files list. + For each stopped AppVM the proxy is killed. - Check that proxy is started so the `pid` field of the show command is a - number: + Check that proxy is started and the `pid` field of the show command is a number: sudo /rw/config/tinyproxy/proxyctl.py show -6. Run the browser in the started AppVM and configure it to use the - proxy on the port 8100 running at the IP address of the firewall VM - gateway interface. In Qubes VM manager the address is given after the - Gateway label in the Setting dialog for the firewall VM. +6. Run the browser in the active AppVM and configure it to use the proxy on port 8100 of the firewall VM gateway interface's IP address. + In Qubes VM manager, the IP address is displayed in the Gateway field in the Settings dialog for the firewall VM. - In Firefox go to the Preferences dialog, select Advanced->Network, - click Settings for the Connection section. In the Connection Settings - dialog select Manual proxy configuration. For HTTP Proxy field use the - IP address of the firewall gateway interface. Enter 8100 as the port - and the select the checkbox "Use this proxy server for all protocols". + In Firefox, go to the Preferences dialog, select Advanced->Network, and click Settings for the Connection section. + In the Connection Settings dialog, select Manual proxy configuration. For the HTTP Proxy field use the IP address of the firewall gateway interface. + Enter 8100 as the port, and select the checkbox "Use this proxy server for all protocols". - Go to some site. The browser should either load it if it was - white-listed in the filtering file or show a page generated by + Go to some web site. + The browser should either load it (if it was white-listed in the filtering file), or show a page generated by tinyproxy that the page was filtered out. - In the firewall VM see `/run/tinyproxy/name/log` file. For each filtered - out website it contains an entry and one can adjust the filtering file - to include the corresponding host. After changing the file run either: - + In the firewall VM see the `/run/tinyproxy/name/log` file. + For each filtered out website it contains an entry, and one can adjust the filtering file to include the corresponding host. + After changing the file, run either: + sudo /rw/config/tinyproxy/proxyctl.py restart name - to restart proxy with the updated rules file only for the given VM or + to restart the proxy with an updated rules file only for the given VM, or sudo /rw/config/tinyproxy/proxyctl.py kill-all-and-restart to restart all proxy processes. -7. To make sure that the proxy is started automatically when the AppVM - starts change `/rw/config/qubes-firewall-user-script` to include the - following line: +7. To make sure that the proxy is started automatically when the AppVM starts, change `/rw/config/qubes-firewall-user-script` to include the following line: /rw/config/tinyproxy/proxyctl.py update @@ -177,19 +132,14 @@ Setup sudo chown root:root /rw/config/qubes-firewall-user-script sudo chmod 755 /rw/config/qubes-firewall-user-script -8. In Qubes VM manager adjust Firewall rules for each AppVM with a - proxy. In a typical case when only HTTP proxy should be used for - outside connections, simply select "Deny network access except...," make - sure that the address list is empty and then unselect "Allow ICMP," "DNS" - and "Update proxy" checkboxes. +8. In Qubes VM manager, adjust the Firewall rules for each AppVM with a proxy. + In a typical case, when only an HTTP proxy should be permitted for outside connections, simply select "Deny network access except...", make sure that the address list is empty, and then unselect the "Allow ICMP," "DNS", and "Update proxy" checkboxes. - There is no need to add any special entries for the proxy in the GUI - as `proxyctl.py` adds rules for the proxy traffic itself. + There is no need to add any special entries for the proxy in the GUI as `proxyctl.py` adds rules for the proxy traffic itself. -------------------------------------------------------------------------------- -This guide was initially written by Igor Bukanov in a [message] to the -`qubes-devel` [mailing list]. +This guide was initially written by Igor Bukanov in a [message] to the `qubes-devel` [mailing list]. [archive]: https://groups.google.com/group/qubes-devel/attach/39c95d63fccca12b/proxy.tar.gz?part=0.1 [message]: https://groups.google.com/d/msg/qubes-devel/UlK8P27UtD4/K6HM_GNdyTkJ From 650511165375349db1f64d91c27f4bb34e395a92 Mon Sep 17 00:00:00 2001 From: awokd <34515595+awokd@users.noreply.github.com> Date: Thu, 22 Feb 2018 12:50:39 +0000 Subject: [PATCH 2/6] additional misc grammar --- configuration/http-filtering-proxy.md | 29 +++++++++++++-------------- 1 file changed, 14 insertions(+), 15 deletions(-) diff --git a/configuration/http-filtering-proxy.md b/configuration/http-filtering-proxy.md index e408a69d..ef49d883 100644 --- a/configuration/http-filtering-proxy.md +++ b/configuration/http-filtering-proxy.md @@ -10,7 +10,7 @@ How to run an HTTP filtering proxy in a FirewallVM Introduction ------------ -By default Qubes uses a special firewall VM that sits between the networking VM and each AppVM. +By default, Qubes uses a special firewall VM that sits between the networking VM and each AppVM. This VM controls the traffic for AppVMs and can be used to restrict what AppVMs can send or receive. The traffic rules can be setup using the filtering rules GUI in Qubes VM manager. The manager translates user-defined setup into iptables rules for the firewall VM's kernel. @@ -32,14 +32,14 @@ Warning ------- Running an HTTP proxy in your firewall VM increases the attack surface against that VM from a compromised AppVM. -Tinyproxy has relatively simple code and a reasonable track record to allow to certain level of trust, but one cannot exclude bugs especially in the case of a hostile proxy clients as this is a less tested scenario. -So it is not advisable to use the proxy in a shared firewall VM against untrusted AppVM to black-list some unwanted connections such as advertisement sites. +Tinyproxy has relatively simple code and a reasonable track record to allow to certain level of trust, but one cannot exclude bugs especially in the case of hostile proxy clients as this is a less tested scenario. +It is not advisable to use the proxy in a shared firewall VM against untrusted AppVM to black-list some unwanted connections such as advertisement sites. A less problematic setup is to white-list possible connections for several trusted and semi-trusted AppVMs within one firewall VM. -Still, for maximum safety one should consider running a separate firewall VM / proxy per each important AppVMs. +Still, for maximum safety one should consider running a separate firewall VM / proxy for each important AppVMs. -As a counterweight to this warning it is important to point out that an HTTP proxy decreases the attack surface of an AppVM. -For example, with a proxy, the AppVM does not need to make direct DNS connections so a bug in the kernel or in the browser in that area would not affect the AppVM. +As a counterpoint to this warning, it is important to note that an HTTP proxy decreases the attack surface of AppVMs. +For example, with a proxy the AppVM does not need to make direct DNS connections, so a bug in the kernel or in the browser in that area would not affect the AppVM. Also, browsers typically avoid many of the latest and greatest HTTP features when connecting through proxies, minimizing exposure of new and unproven networking code. @@ -53,7 +53,7 @@ Setup 2. If necessary, adjust `/rw/config/tinyproxy/config` according to the man page for `tinyproxy.conf`. The included config file refuses the connection unless the host is white-listed in the filtering file, so this can be altered if one prefers to black-list connections. - One may also specify upstream proxies there. + One may also specify upstream proxies here. The file is a template file and the control script will replace `{name}` constructs in the file with actual parameters. In general, lines with `{}` should be preserved as is. @@ -64,10 +64,10 @@ Setup name.ip-address-of-app-vm - The name part before the dot is arbitrary. + The name before the dot is arbitrary. For convenience, one can use an AppVM name here, but this is not required. - It is important to get the ip address part right as this is what the control script uses to determine on which AppVM it will apply the proxy rules. - One can check the IP address of AppVM in Qubes VM manager in the VM settings dialog; see the Networking session under the Basic tab. + It is important to get the ip address part right, as this is what the control script uses to determine to which AppVM it will apply the proxy rules. + One can check the IP address of an AppVM in Qubes VM manager in the VM settings dialog; see the Networking settings under the Basic tab. The attached archive includes a `tinyproxy/social.10.137.2.13` file with rules for an AppVM allowing connections to Google, Facebook, Linkedin, Livejournal, Youtube, and few other other sites. One can use it as an example after changing the IP addresses accordingly. @@ -89,7 +89,7 @@ Setup sudo /rw/config/tinyproxy/proxyctl.py update The update command starts proxy processes and adjusts the iptable rules to allow for proxy traffic for each running AppVM from the filtering files list. - For each stopped AppVM the proxy is killed. + For each stopped AppVM, the proxy is killed. Check that proxy is started and the `pid` field of the show command is a number: @@ -102,11 +102,10 @@ Setup In the Connection Settings dialog, select Manual proxy configuration. For the HTTP Proxy field use the IP address of the firewall gateway interface. Enter 8100 as the port, and select the checkbox "Use this proxy server for all protocols". - Go to some web site. - The browser should either load it (if it was white-listed in the filtering file), or show a page generated by - tinyproxy that the page was filtered out. + Go to a test web site. + The browser should either load it (if it was white-listed in the filtering file), or show a page generated by tinyproxy that the page was filtered out. - In the firewall VM see the `/run/tinyproxy/name/log` file. + In the firewall VM, see the `/run/tinyproxy/name/log` file. For each filtered out website it contains an entry, and one can adjust the filtering file to include the corresponding host. After changing the file, run either: From 4ab031a2188ad39934a09f6987b07eb9c7eca10a Mon Sep 17 00:00:00 2001 From: awokd <34515595+awokd@users.noreply.github.com> Date: Sat, 24 Feb 2018 09:24:08 +0000 Subject: [PATCH 3/6] R3.2 updates --- configuration/http-filtering-proxy.md | 23 +++++++++++++---------- 1 file changed, 13 insertions(+), 10 deletions(-) diff --git a/configuration/http-filtering-proxy.md b/configuration/http-filtering-proxy.md index ef49d883..e5eacaaf 100644 --- a/configuration/http-filtering-proxy.md +++ b/configuration/http-filtering-proxy.md @@ -27,6 +27,9 @@ As a workaround, one can use a browser's network console to see what is blocked, These drawbacks can be mitigated if one replaces iptable-based rules with a filtering HTTP proxy. The following describes how to setup a tinyproxy-based proxy in the firewall VM to achieve such filtering. +**Note** This content only describes setup of an HTTP proxy. +This will handle web browsing using HTTP and HTTPS, but this type of proxy does not support other protocols such as IMAP used in Thunderbird. +For that, you need a fully featured proxy which is beyond the scope of this article. Warning ------- @@ -36,7 +39,7 @@ Tinyproxy has relatively simple code and a reasonable track record to allow to c It is not advisable to use the proxy in a shared firewall VM against untrusted AppVM to black-list some unwanted connections such as advertisement sites. A less problematic setup is to white-list possible connections for several trusted and semi-trusted AppVMs within one firewall VM. -Still, for maximum safety one should consider running a separate firewall VM / proxy for each important AppVMs. +Still, for maximum safety one should consider running a separate proxy VM for each important AppVM. As a counterpoint to this warning, it is important to note that an HTTP proxy decreases the attack surface of AppVMs. For example, with a proxy the AppVM does not need to make direct DNS connections, so a bug in the kernel or in the browser in that area would not affect the AppVM. @@ -46,7 +49,7 @@ Also, browsers typically avoid many of the latest and greatest HTTP features whe Setup ----- -1. Copy this [archive] with the proxy control script, default tinyproxy config and a sample firewall filtering file into the firewall VM and unpack it in `/rw/config` folder there as root: +1. Copy this [archive] with the proxy control script, default tinyproxy config, and a sample firewall filtering file into the firewall VM and unpack it in the `/rw/config` folder there as root: cd /rw/config sudo tar xzf .../proxy.tar.xz @@ -70,7 +73,7 @@ Setup One can check the IP address of an AppVM in Qubes VM manager in the VM settings dialog; see the Networking settings under the Basic tab. The attached archive includes a `tinyproxy/social.10.137.2.13` file with rules for an AppVM allowing connections to Google, Facebook, Linkedin, Livejournal, Youtube, and few other other sites. - One can use it as an example after changing the IP addresses accordingly. + One can use it as an example after changing the IP address accordingly. When editing the rules, remember to include a `$` at the end of the host name, and to prefix each dot in the host name with a backslash (like `\.`). This way, the pattern matches the whole host and not just a prefix, and the dot is not interpreted as an instruction to match an arbitrary character according to regular expression syntax. @@ -82,9 +85,9 @@ Setup For each rule file it should print the name, ip address, and network interface of the running AppVMs. It will also display the id of the tinyproxy process that proxies that AppVM. - The first time, each pid should be `--`. + Each pid will be `--` because we have no running proxies yet. -5. Now run some AppVM with a proxy, and then run: +5. Now, start the AppVM for which you created a rule file, and then run: sudo /rw/config/tinyproxy/proxyctl.py update @@ -96,7 +99,7 @@ Setup sudo /rw/config/tinyproxy/proxyctl.py show 6. Run the browser in the active AppVM and configure it to use the proxy on port 8100 of the firewall VM gateway interface's IP address. - In Qubes VM manager, the IP address is displayed in the Gateway field in the Settings dialog for the firewall VM. + In Qubes VM manager, the IP address is displayed in the Gateway field in the Settings dialog for the AppVM. In Firefox, go to the Preferences dialog, select Advanced->Network, and click Settings for the Connection section. In the Connection Settings dialog, select Manual proxy configuration. For the HTTP Proxy field use the IP address of the firewall gateway interface. @@ -105,11 +108,11 @@ Setup Go to a test web site. The browser should either load it (if it was white-listed in the filtering file), or show a page generated by tinyproxy that the page was filtered out. - In the firewall VM, see the `/run/tinyproxy/name/log` file. + In the firewall VM, see the `/run/tinyproxy//log` file. For each filtered out website it contains an entry, and one can adjust the filtering file to include the corresponding host. After changing the file, run either: - sudo /rw/config/tinyproxy/proxyctl.py restart name + sudo /rw/config/tinyproxy/proxyctl.py restart to restart the proxy with an updated rules file only for the given VM, or @@ -123,7 +126,7 @@ Setup If the file does not exist, create it so it looks like this: - #!/usr/bin/bash + #!/bin/sh /rw/config/tinyproxy/proxyctl.py update Make sure that the script is owned by root and executable: @@ -132,7 +135,7 @@ Setup sudo chmod 755 /rw/config/qubes-firewall-user-script 8. In Qubes VM manager, adjust the Firewall rules for each AppVM with a proxy. - In a typical case, when only an HTTP proxy should be permitted for outside connections, simply select "Deny network access except...", make sure that the address list is empty, and then unselect the "Allow ICMP," "DNS", and "Update proxy" checkboxes. + In a typical case, when only the HTTP proxy should be permitted for outside connections, simply select "Deny network access except...", make sure that the address list is empty, and then unselect the "Allow ICMP," "DNS", and "Update proxy" checkboxes. There is no need to add any special entries for the proxy in the GUI as `proxyctl.py` adds rules for the proxy traffic itself. From 66389fc14a4bec13ca8cbc4cc743f03a065e4f70 Mon Sep 17 00:00:00 2001 From: awokd <34515595+awokd@users.noreply.github.com> Date: Sat, 24 Feb 2018 10:40:21 +0000 Subject: [PATCH 4/6] R4.0 updates replace most references to "firewall VM" with "proxy VM" to discourage use of sys-firewall add R4.0 specific procedures label R3.2 specific procedures correct AppVM's gateway vs. firewall's gateway --- configuration/http-filtering-proxy.md | 46 +++++++++++++++++---------- 1 file changed, 30 insertions(+), 16 deletions(-) diff --git a/configuration/http-filtering-proxy.md b/configuration/http-filtering-proxy.md index e5eacaaf..118eef3c 100644 --- a/configuration/http-filtering-proxy.md +++ b/configuration/http-filtering-proxy.md @@ -29,17 +29,19 @@ The following describes how to setup a tinyproxy-based proxy in the firewall VM **Note** This content only describes setup of an HTTP proxy. This will handle web browsing using HTTP and HTTPS, but this type of proxy does not support other protocols such as IMAP used in Thunderbird. -For that, you need a fully featured proxy which is beyond the scope of this article. +For that, you need a fully featured SOCKS proxy such as Squid which is beyond the scope of this article. Warning ------- Running an HTTP proxy in your firewall VM increases the attack surface against that VM from a compromised AppVM. Tinyproxy has relatively simple code and a reasonable track record to allow to certain level of trust, but one cannot exclude bugs especially in the case of hostile proxy clients as this is a less tested scenario. -It is not advisable to use the proxy in a shared firewall VM against untrusted AppVM to black-list some unwanted connections such as advertisement sites. +It is not advisable to use the proxy in a shared firewall VM against untrusted AppVMs to black-list some unwanted connections such as advertisement sites. A less problematic setup is to white-list possible connections for several trusted and semi-trusted AppVMs within one firewall VM. -Still, for maximum safety one should consider running a separate proxy VM for each important AppVM. +Still, for maximum safety, one should consider running a separate ProxyVM for each important AppVM. + +In Qubes R4.0, one no longer creates ProxyVMs as such. However, the same is accomplished by choosing the `provides network` checkbox when creating an AppVM that will be used as a proxy. As a counterpoint to this warning, it is important to note that an HTTP proxy decreases the attack surface of AppVMs. For example, with a proxy the AppVM does not need to make direct DNS connections, so a bug in the kernel or in the browser in that area would not affect the AppVM. @@ -49,18 +51,25 @@ Also, browsers typically avoid many of the latest and greatest HTTP features whe Setup ----- -1. Copy this [archive] with the proxy control script, default tinyproxy config, and a sample firewall filtering file into the firewall VM and unpack it in the `/rw/config` folder there as root: +1. After reading through the Warning section above, determine if you want to proceed with the following steps in either your default `sys-firewall` VM or in a newly created proxy VM. + If you decide to create a separate proxy VM, + * In R4.0, create a new AppVM with the `provides network` checkbox set. + * In R3.2, create a new ProxyVM. + + Then, proceed with the following. + +2. Copy this [archive] with the proxy control script, default tinyproxy config, and a sample filtering file into the proxy VM and unpack it in the `/rw/config` folder there as root: cd /rw/config sudo tar xzf .../proxy.tar.xz -2. If necessary, adjust `/rw/config/tinyproxy/config` according to the man page for `tinyproxy.conf`. +3. If necessary, adjust `/rw/config/tinyproxy/config` according to the man page for `tinyproxy.conf`. The included config file refuses the connection unless the host is white-listed in the filtering file, so this can be altered if one prefers to black-list connections. One may also specify upstream proxies here. The file is a template file and the control script will replace `{name}` constructs in the file with actual parameters. In general, lines with `{}` should be preserved as is. -3. For each AppVM that one wants to run through the proxy, create a corresponding filtering file in the `/rw/config/tinyproxy` directory. +4. For each AppVM that one wants to run through the proxy, create a corresponding filtering file in the `/rw/config/tinyproxy` directory. With the default config, the filtering file should contain regular expressions to match white-listed hosts with one regular expression per line. See the man page for tinyproxy.conf for details. The file should be named: @@ -69,16 +78,19 @@ Setup The name before the dot is arbitrary. For convenience, one can use an AppVM name here, but this is not required. + It is important to get the ip address part right, as this is what the control script uses to determine to which AppVM it will apply the proxy rules. - One can check the IP address of an AppVM in Qubes VM manager in the VM settings dialog; see the Networking settings under the Basic tab. + If you have created a separate proxy VM, change the `NetVM` of each AppVM that will be using it to the proxy VM. + That can be done in Qubes VM manager in the VM settings dialog under the Basic tab. + Next, see the Networking settings on the same tab to check the IP address of an AppVM. - The attached archive includes a `tinyproxy/social.10.137.2.13` file with rules for an AppVM allowing connections to Google, Facebook, Linkedin, Livejournal, Youtube, and few other other sites. + The attached archive includes a `social.10.137.2.13` file with rules for an AppVM allowing connections to Google, Facebook, Linkedin, Livejournal, Youtube, and few other other sites. One can use it as an example after changing the IP address accordingly. When editing the rules, remember to include a `$` at the end of the host name, and to prefix each dot in the host name with a backslash (like `\.`). This way, the pattern matches the whole host and not just a prefix, and the dot is not interpreted as an instruction to match an arbitrary character according to regular expression syntax. -4. Check that the `proxyctl.py` script can properly recognize the rule files. +5. Check that the `proxyctl.py` script can properly recognize the rule files. For that, run: sudo /rw/config/tinyproxy/proxyctl.py show @@ -87,7 +99,7 @@ Setup It will also display the id of the tinyproxy process that proxies that AppVM. Each pid will be `--` because we have no running proxies yet. -5. Now, start the AppVM for which you created a rule file, and then run: +6. Now, start the AppVM for which you created a rule file, and then run: sudo /rw/config/tinyproxy/proxyctl.py update @@ -98,17 +110,17 @@ Setup sudo /rw/config/tinyproxy/proxyctl.py show -6. Run the browser in the active AppVM and configure it to use the proxy on port 8100 of the firewall VM gateway interface's IP address. +7. Run the browser in the active AppVM and configure it to use the proxy on port 8100 of the proxy VM interface's IP address. In Qubes VM manager, the IP address is displayed in the Gateway field in the Settings dialog for the AppVM. In Firefox, go to the Preferences dialog, select Advanced->Network, and click Settings for the Connection section. - In the Connection Settings dialog, select Manual proxy configuration. For the HTTP Proxy field use the IP address of the firewall gateway interface. + In the Connection Settings dialog, select Manual proxy configuration. For the HTTP Proxy field use the IP address of the AppVM's gateway. Enter 8100 as the port, and select the checkbox "Use this proxy server for all protocols". Go to a test web site. The browser should either load it (if it was white-listed in the filtering file), or show a page generated by tinyproxy that the page was filtered out. - In the firewall VM, see the `/run/tinyproxy//log` file. + In the proxy VM, see the `/run/tinyproxy//log` file. For each filtered out website it contains an entry, and one can adjust the filtering file to include the corresponding host. After changing the file, run either: @@ -120,7 +132,7 @@ Setup to restart all proxy processes. -7. To make sure that the proxy is started automatically when the AppVM starts, change `/rw/config/qubes-firewall-user-script` to include the following line: +8. To make sure that the proxy is started automatically when the AppVM starts, change `/rw/config/qubes-firewall-user-script` to include the following line: /rw/config/tinyproxy/proxyctl.py update @@ -134,8 +146,10 @@ Setup sudo chown root:root /rw/config/qubes-firewall-user-script sudo chmod 755 /rw/config/qubes-firewall-user-script -8. In Qubes VM manager, adjust the Firewall rules for each AppVM with a proxy. - In a typical case, when only the HTTP proxy should be permitted for outside connections, simply select "Deny network access except...", make sure that the address list is empty, and then unselect the "Allow ICMP," "DNS", and "Update proxy" checkboxes. +9. In Qubes VM manager, adjust the Firewall rules for each AppVM using a proxy. + In a typical case, when only the HTTP proxy should be permitted for outside connections: + * In R4.0, select "Limit outgoing Internet connections to..." and make sure the address list is empty. + * In R3.2, select "Deny network access except...", make sure the address list is empty, and then unselect the "Allow ICMP," "DNS", and "Update proxy" checkboxes. There is no need to add any special entries for the proxy in the GUI as `proxyctl.py` adds rules for the proxy traffic itself. From 3f971d9ab15c14396ab92c0db14a4903b98a1a2d Mon Sep 17 00:00:00 2001 From: awokd <34515595+awokd@users.noreply.github.com> Date: Sat, 24 Feb 2018 10:48:34 +0000 Subject: [PATCH 5/6] make proxy VM less sys-firewall specific --- configuration/http-filtering-proxy.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/configuration/http-filtering-proxy.md b/configuration/http-filtering-proxy.md index 118eef3c..9ab5249c 100644 --- a/configuration/http-filtering-proxy.md +++ b/configuration/http-filtering-proxy.md @@ -4,7 +4,7 @@ title: HTTP Filtering Proxy permalink: /doc/config/http-filtering-proxy/ --- -How to run an HTTP filtering proxy in a FirewallVM +How to run an HTTP filtering proxy ================================================= Introduction @@ -25,7 +25,7 @@ Third, the initial setup of the rules is complicated as the firewall drops the c As a workaround, one can use a browser's network console to see what is blocked, but this is time-consuming and one can easily miss some important cases like including sites for OCSP SSL certificate verification in the firewall white-list. These drawbacks can be mitigated if one replaces iptable-based rules with a filtering HTTP proxy. -The following describes how to setup a tinyproxy-based proxy in the firewall VM to achieve such filtering. +The following describes how to setup a tinyproxy-based proxy in either the firewall VM or a custom proxy VM to achieve such filtering. **Note** This content only describes setup of an HTTP proxy. This will handle web browsing using HTTP and HTTPS, but this type of proxy does not support other protocols such as IMAP used in Thunderbird. From 29278a591e7ef32cec96424e18167a0133f0ac03 Mon Sep 17 00:00:00 2001 From: awokd <34515595+awokd@users.noreply.github.com> Date: Sat, 24 Feb 2018 10:49:47 +0000 Subject: [PATCH 6/6] make http proxy less sys-firewall specific --- doc.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc.md b/doc.md index a1ed41bb..a184a8cb 100644 --- a/doc.md +++ b/doc.md @@ -132,7 +132,7 @@ Configuration Guides * [Fetchmail Guide](/doc/fetchmail/) * [Creating Custom NetVMs and ProxyVMs](https://theinvisiblethings.blogspot.com/2011/09/playing-with-qubes-networking-for-fun.html) * [How to make proxy for individual tcp connection from networkless VM](https://groups.google.com/group/qubes-devel/msg/4ca950ab6d7cd11a) - * [Make an HTTP Filtering Proxy in a FirewallVM](/doc/config/http-filtering-proxy) + * [Make an HTTP Filtering Proxy](/doc/config/http-filtering-proxy) * [Adding Bridge Support to the NetVM (EXPERIMENTAL)](/doc/network-bridge-support/) * [Assigning PCI Devices to AppVMs](/doc/assigning-devices/) * [Enabling TRIM for SSD disks](/doc/disk-trim/)