suzanne.soy/qubes-doc
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

line breaks, misc grammar

Browse Source
This commit is contained in:
awokd 2018-02-22 12:38:21 +00:00 committed by GitHub
parent 7f5b164a48
commit 82a26e5bc0
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 64 additions and 114 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

178
configuration/http-filtering-proxy.md
View File

@ -10,160 +10,115 @@ How to run an HTTP filtering proxy in a FirewallVM
Introduction Introduction
------------ ------------
By default Qubes uses a special firewall VM that sits between the By default Qubes uses a special firewall VM that sits between the networking VM and each AppVM.
networking VM and each AppVM. This VM controls the traffic for AppVMs This VM controls the traffic for AppVMs and can be used to restrict what AppVMs can send or receive.
and can be used to restrict what AppVMs can send or receive. The The traffic rules can be setup using the filtering rules GUI in Qubes VM manager.
traffic rules can be setup using filtering rules GUI in Qubes VM The manager translates user-defined setup into iptables rules for the firewall VM's kernel.
manager. The manager translates user-defined setup into iptables rules
for the kernel of firewall VM.
The primary goal of the filtering rule setup in firewall VM is to 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).
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).
As the rules in the firewall are IP-based, it has drawbacks. First the As the rules in the firewall are IP-based, it has drawbacks.
rules cannot be used if one has to use a HTTP proxy to connect for First, the rules cannot be used if one has to use an HTTP proxy to connect to websites (a common setup on corporate networks).
websites (a common setup on corporate networks). Second the Qubes Second, Qubes resolves DNS names from the firewall rules when the AppVM loads.
resolves DNS names from the firewall rules when the AppVM loads. This 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.
prevents websites that use DNS-based load balancers from working Third, the initial setup of the rules is complicated as the firewall drops the connection silently.
unless the user reloads the firewall rules (which re-resolve the DNS 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.
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.
These drawbacks can be mitigated if one replaces iptable-based rules These drawbacks can be mitigated if one replaces iptable-based rules with a filtering HTTP proxy.
with a filtering HTTP proxy. The following describes how to setup The following describes how to setup a tinyproxy-based proxy in the firewall VM to achieve such filtering.
tinyproxy-based proxy in the firewall VM to archive such filtering.
Warning Warning
------- -------
Running a HTTP proxy in your firewall VM increases the attack surface Running an HTTP proxy in your firewall VM increases the attack surface against that VM from a compromised AppVM.
against that VM from a compromised AppVM. tinyproxy has a relatively 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.
simple code and a reasonable track record to allow to certain level of 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.
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.
Less problematic setup is to white-list possible connections for A less problematic setup is to white-list possible connections for several trusted and semi-trusted AppVMs within one firewall VM.
several trusted and semi-trusted AppVMs within one firewall VM. Still Still, for maximum safety one should consider running a separate firewall VM / proxy per each important AppVMs.
for maximum safety one should consider running a separated firewall VM
per each important AppVMs and run the proxy there.
As a counterweight to this warning it is important to point out that As a counterweight to this warning it is important to point out that an HTTP proxy decreases the attack surface of an AppVM.
HTTP proxy decreases attack surface against AppVM. For example, with a 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.
proxy the AppVM does not need DNS connections so a bug in the kernel Also, browsers typically avoid many of the latest and greatest HTTP features when connecting through proxies, minimizing exposure of new and unproven networking code.
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.
Setup Setup
----- -----
1. Copy this [archive] with the proxy control script, default 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:
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 cd /rw/config
sudo tar xzf .../proxy.tar.xz sudo tar xzf .../proxy.tar.xz
2. If necessary adjust `/rw/config/tinyproxy/config` according to the 2. If necessary, adjust `/rw/config/tinyproxy/config` according to the man page for `tinyproxy.conf`.
man page for `tinyproxy.conf`. The included config file refuses the 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.
connection unless the host is white-listed in the filtering file, so One may also specify upstream proxies there.
this can be altered if one wants rather to black-list connection. One The file is a template file and the control script will replace `{name}` constructs in the file with actual parameters.
may also specify upstream proxies there. The file is a template file In general, lines with `{}` should be preserved as is.
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 3. For each AppVM that one wants to run through the proxy, create a corresponding filtering file in the `/rw/config/tinyproxy` directory.
the corresponding filtering file in the `/rw/config/tinyproxy` With the default config, the filtering file should contain regular expressions to match white-listed hosts with one regular expression per line.
directory. With the default config the filtering file should contain See the man page for tinyproxy.conf for details.
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: The file should be named:
name.ip-address-of-app-vm name.ip-address-of-app-vm
The name part before the dot can be arbitrary. For convenience one can The name part before the dot is arbitrary.
use AppVM name here, but this is not required. It is important to get For convenience, one can use an AppVM name here, but this is not required.
ip address part right as this is what the control script uses to 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.
determine for which AppVM to apply the proxy rules. One can check the 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.
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 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.
rules for a AppVM allowing connection to google, facebook, linkedin, One can use it as an example after changing the IP addresses accordingly.
livejournal, youtube and few other other sites. One can use it as an
example after changing the the IP address accordingly.
When editing the rules remember to include `$` at the end of the host 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 `\.`).
name and to prefix each dot in the host name with the backslash. This 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.
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.
4. Check that `proxyctl.py` script can properly recognize the rule 4. Check that the `proxyctl.py` script can properly recognize the rule files.
files. For that run: For that, run:
sudo /rw/config/tinyproxy/proxyctl.py show sudo /rw/config/tinyproxy/proxyctl.py show
For each rule file it should print the name, ip address, network For each rule file it should print the name, ip address, and network interface of the running AppVMs.
interface of the running AppVM if AppVM runs and the id of the It will also display the id of the tinyproxy process that proxies that AppVM.
tinyproxy process that proxies that AppVM. The first time each pid The first time, each pid should be `--`.
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 sudo /rw/config/tinyproxy/proxyctl.py update
The update command starts proxy processes and adjusts the iptable 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.
rules to allow for proxy traffic for each running AppVM from the For each stopped AppVM the proxy is killed.
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 Check that proxy is started and the `pid` field of the show command is a number:
number:
sudo /rw/config/tinyproxy/proxyctl.py show sudo /rw/config/tinyproxy/proxyctl.py show
6. Run the browser in the started AppVM and configure it to use the 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.
proxy on the port 8100 running at the IP address of the firewall VM In Qubes VM manager, the IP address is displayed in the Gateway field in the Settings dialog for 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.
In Firefox go to the Preferences dialog, select Advanced->Network, In Firefox, go to the Preferences dialog, select Advanced->Network, and click Settings for the Connection section.
click Settings for the Connection section. In the Connection Settings In the Connection Settings dialog, select Manual proxy configuration. For the HTTP Proxy field use the IP address of the firewall gateway interface.
dialog select Manual proxy configuration. For HTTP Proxy field use the Enter 8100 as the port, and select the checkbox "Use this proxy server for all protocols".
IP address of the firewall gateway interface. Enter 8100 as the port
and the select the checkbox "Use this proxy server for all protocols".
Go to some site. The browser should either load it if it was Go to some web site.
white-listed in the filtering file or show a page generated by 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. tinyproxy that the page was filtered out.
In the firewall VM see `/run/tinyproxy/name/log` file. For each filtered In the firewall VM see the `/run/tinyproxy/name/log` file.
out website it contains an entry and one can adjust the filtering file For each filtered out website it contains an entry, and one can adjust the filtering file to include the corresponding host.
to include the corresponding host. After changing the file run either: After changing the file, run either:
sudo /rw/config/tinyproxy/proxyctl.py restart name 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 sudo /rw/config/tinyproxy/proxyctl.py kill-all-and-restart
to restart all proxy processes. to restart all proxy processes.
7. To make sure that the proxy is started automatically when the AppVM 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:
starts change `/rw/config/qubes-firewall-user-script` to include the
following line:
/rw/config/tinyproxy/proxyctl.py update /rw/config/tinyproxy/proxyctl.py update
@ -177,19 +132,14 @@ Setup
sudo chown root:root /rw/config/qubes-firewall-user-script sudo chown root:root /rw/config/qubes-firewall-user-script
sudo chmod 755 /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 8. In Qubes VM manager, adjust the Firewall rules for each AppVM with a proxy.
proxy. In a typical case when only HTTP proxy should be used for 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.
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.
There is no need to add any special entries for the proxy in the GUI 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.
as `proxyctl.py` adds rules for the proxy traffic itself.
-------------------------------------------------------------------------------- --------------------------------------------------------------------------------
This guide was initially written by Igor Bukanov in a [message] to the This guide was initially written by Igor Bukanov in a [message] to the `qubes-devel` [mailing list].
`qubes-devel` [mailing list].
[archive]: https://groups.google.com/group/qubes-devel/attach/39c95d63fccca12b/proxy.tar.gz?part=0.1 [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 [message]: https://groups.google.com/d/msg/qubes-devel/UlK8P27UtD4/K6HM_GNdyTkJ