doc/TorBrowser/SmartOS_Sandboxing.md

 
 [[PageOutline]]
 
-= The Tor Browser SmartOS Sandboxing Guide =
+# The Tor Browser SmartOS Sandboxing Guide
 
-This page provides instructions for sandboxing the Linux build of Tor Browser Bundle using the [https://wiki.smartos.org/display/DOC/Home SmartOS hypervisor] with the [https://wiki.illumos.org/display/illumos/illumos+Home IllumOS kernel] such that the Browser is only able to access the `SocksPort` of a `tor` instance running in another security domain. We make use of native Solaris [https://wiki.smartos.org/display/DOC/Zones zones] for running `tor` and a firewall, and Solaris' [https://wiki.smartos.org/display/DOC/LX+Branded+Zones Linux-Branded Zones] (which emulate Linux system calls, and can run both x86 32-bit and 64-bit Linux binaries) for running Tor Browser. We also provide instructions for using the browser-based NoVNC client to access the sandboxed Tor Browser (eg, from another Tor Browser running locally).
+This page provides instructions for sandboxing the Linux build of Tor Browser Bundle using the [SmartOS hypervisor](https://wiki.smartos.org/display/DOC/Home) with the [IllumOS kernel](https://wiki.illumos.org/display/illumos/illumos+Home) such that the Browser is only able to access the `SocksPort` of a `tor` instance running in another security domain. We make use of native Solaris [zones](https://wiki.smartos.org/display/DOC/Zones) for running `tor` and a firewall, and Solaris' [Linux-Branded Zones](https://wiki.smartos.org/display/DOC/LX+Branded+Zones) (which emulate Linux system calls, and can run both x86 32-bit and 64-bit Linux binaries) for running Tor Browser. We also provide instructions for using the browser-based NoVNC client to access the sandboxed Tor Browser (eg, from another Tor Browser running locally).
 
-'''The Linux Tor Browser binary runs just fine in a Linux zone on Solaris/SmartOS!'''
+**The Linux Tor Browser binary runs just fine in a Linux zone on Solaris/SmartOS!**
 
 Our sandbox environment will have several components which will each be in their own zone. The Tor Browser will run with a X server created by vnc4server. A stealth authenticated onion service will expose an HTTP service via noVNC which will serve an HTML5 VNC client to the browser and it will connect to the zone running the Tor Browser vnc4server.
 
@@ -17,7 +17,7 @@ Our sandbox environment will have several components which will each be in their
 * Tor Browser + vnc4server
 * the webserver component of noVNC
 
-== why? ==
+## why?
 
 * use of dtrace
 * use of ZFS to take snapshots and rollback to previous snapshots
@@ -26,12 +26,12 @@ Our sandbox environment will have several components which will each be in their
 * less overhead than Linux virtualization
 * remote execution vulnerability not likely to exploit kernel since we aren't running the Linux kernel
 
-== global zone configuration ==
+## global zone configuration
 
 I recommend that the global zone have several changes such as disabling ssh password login, changing the ssh listening port and using strict firewall rules.
 
-my '''/usbkey/config''' looks like this:
-{{{
+my **/usbkey/config** looks like this:
+```
 admin_nic=MM:MM:MM:MM:MM:MM
 admin_ip=dhcp
 headnode_default_gateway=none
@@ -41,10 +41,10 @@ ntp_hosts=0.pool.ntp.org
 hostname=computer
 root_authorized_keys_file=authorized_keys
 etherstub="switch0"
-}}}
+```
 
-firewall rules in '''/etc/ipf/ipf.conf'''; you'll have to change the rule for your DNS resolver IPv4 address and I also recommend that you not use ssh port 22 but instead pick a high port number:
-{{{
+firewall rules in **/etc/ipf/ipf.conf**; you'll have to change the rule for your DNS resolver IPv4 address and I also recommend that you not use ssh port 22 but instead pick a high port number:
+```
 #
 # ipf.conf
 #
@@ -138,16 +138,16 @@ pass in quick proto tcp from any to any port = 22 flags S/FSRPAU keep state keep
 # Block and log only first occurrence of all remaining traffic.
 block in log first quick on vioif0 all
 
-}}}
+```
 
 
 
-== creation of zones ==
+## creation of zones
 
-Read the SmartOS documentation on [https://wiki.smartos.org/display/DOC/Managing+Images zone image management].
+Read the SmartOS documentation on [zone image management](https://wiki.smartos.org/display/DOC/Managing+Images).
 We create Solaris and Linux zones using the latest SmartOS zone images available:
 
-{{{
+```
 imgadm avail | grep debian-8 | grep lx-dataset | tail -n 1
 445d04f4-cad6-11e5-a1a0-9f6c0ce02707  debian-8                20160204    linux    lx-dataset    2016-02-04
 
@@ -156,16 +156,16 @@ imgadm avail |grep base-64-lts | tail -n 1
 
 imgadm import 445d04f4-cad6-11e5-a1a0-9f6c0ce02707
 imgadm import 96bcddda-beb7-11e5-af20-a3fb54c8ae29
-}}}
+```
 
 These two image IDs will be specified in our zone manifests.
-Refer to [https://wiki.smartos.org/display/DOC/How+to+create+a+zone+%28+OS+virtualized+machine+%29+in+SmartOS creating zones with SmartOS] for more information.
+Refer to [creating zones with SmartOS](https://wiki.smartos.org/display/DOC/How+to+create+a+zone+%28+OS+virtualized+machine+%29+in+SmartOS) for more information.
 
 
-== firewall zone ==
+## firewall zone
 
-create a '''firewall.json''' file where public IPv4 address is '''XXX.XXX.XXX.XXX''' and the gateway is '''YYY.YYY.YYY.YYY''' :
-{{{
+create a **firewall.json** file where public IPv4 address is **XXX.XXX.XXX.XXX** and the gateway is **YYY.YYY.YYY.YYY** :
+```
 {
   "alias": "firewall",
   "hostname": "firewall",
@@ -191,16 +191,16 @@ create a '''firewall.json''' file where public IPv4 address is '''XXX.XXX.XXX.XX
     }
   ]
 }
-}}}
+```
 
 create the zone:
-{{{
+```
 vmadm create -f firewall.json
-}}}
+```
 
 
 login
-{{{
+```
 vmadm list
 UUID                                  TYPE  RAM      STATE             ALIAS
 5d9ab9da-8aae-4a48-b73a-b7ae574a5dd3  OS    500      running           firewall
@@ -216,31 +216,30 @@ Last login: Fri Mar  4 10:33:05 on pts/13
                    `-'  https://docs.joyent.com/images/smartos/base
 
 [root@firewall ~]# 
-}}}
+```
 
-firewall NAT configuration in '''/etc/ipf/ipfnat.conf'''
-{{{
+firewall NAT configuration in **/etc/ipf/ipfnat.conf**
+```
 ipfnat.conf 
 map net0 10.0.0.2/24 -> 0/32 portmap tcp/udp auto
 map net0 10.0.0.2/24 -> 0/32
-}}}
+```
 
-firewall filtering in '''/etc/ipf/ipf.conf'''
-{{{
+firewall filtering in **/etc/ipf/ipf.conf**
+```
 block out from 10.0.0.13/32
 block in from 10.0.0.13/32
-}}}
+```
 
-'''/opt/custom/bin/net-setup'''
-{{{
-#!/usr/bin/bash
+**/opt/custom/bin/net-setup**
+```
 
 ipnat -v -f /etc/ipf/ipfnat.conf
 
-}}}
+```
 
-'''/opt/custom/smf/net-setup.xml'''
-{{{
+**/opt/custom/smf/net-setup.xml**
+```
 <?xml version="1.0"?>
 <!DOCTYPE service_bundle SYSTEM "/usr/share/lib/xml/dtd/service_bundle.dtd.1">
  
@@ -265,27 +264,27 @@ ipnat -v -f /etc/ipf/ipfnat.conf
         <stability value='Unstable' />
 </service>
 </service_bundle>
-}}}
+```
 
 
-{{{
+```
 routeadm -u -e ipv4-forwarding
 svcadm enable route
 svcadm enable ipfilter
 svccfg import /opt/custom/smf/net-setup.xml
 ipf -Fa -f /etc/ipf/ipf.conf
 ipnat -f /etc/ipf/ipfnat.conf
-}}}
+```
 
 
-== onion tor zone ==
+## onion tor zone
 
 This zone will run tor for our onion service.
 We could use a Solaris or Linux zone since tor works in either one.
 Here I'll describe how I do it with the latest Linux debian-8 zone:
 
-'''lx-onion-tor.json'''
-{{{
+**lx-onion-tor.json**
+```
 {
   "alias": "lx-onion-tor",
   "brand": "lx",
@@ -303,52 +302,52 @@ Here I'll describe how I do it with the latest Linux debian-8 zone:
     }
   ]
 }
-}}}
+```
 
-{{{
+```
 vmadm create -f lx-onion-tor.json
 vmadm list
 UUID                                  TYPE  RAM      STATE             ALIAS
 5b2707ac-6175-45b4-d618-92802e3870fd  LX    400      running           lx-onion-tor
 5d9ab9da-8aae-4a48-b73a-b7ae574a5dd3  OS    500      running           firewall
-}}}
+```
 
 update and upgrade
-{{{
+```
 zlogin 5b2707ac-6175-45b4-d618-92802e3870fd
 apt-get update
 apt-get upgrade
 apt-get install tor
-}}}
+```
 
 
 setup our torrc with our stealth authenticated onion service
-by adding these lines to '''/etc/tor/torrc'''
-{{{
+by adding these lines to **/etc/tor/torrc**
+```
 HiddenServiceDir /var/lib/tor/hidden_service/
 HiddenServiceAuthorizeClient stealth client1
 HiddenServicePort 6001 10.0.0.8:6001
-}}}
+```
 
-{{{
+```
 systemctl restart tor
-}}}
+```
 
-After tor starts and uploads the onion service descriptors you can look in the '''/var/lib/tor/hidden_service/'''
+After tor starts and uploads the onion service descriptors you can look in the **/var/lib/tor/hidden_service/**
 and retrieve your client token and onion address. You'll have to add this information into your client torrc
 to be able to connect to this onion service; like this:
 
-{{{
+```
 HidServAuth <ONION> <SECRET_TOKEN>
-}}}
+```
 
 
-== onion vnc server ==
+## onion vnc server
 
 This zone will run the noVNC http server which acts as a VNC client.
 
 lx-noVNC.json:
-{{{
+```
 {
   "alias": "lx-noVNC",
   "brand": "lx",
@@ -366,11 +365,11 @@ lx-noVNC.json:
     }
   ]
 }
-}}}
+```
 
 
 create the new noVNC zone
-{{{
+```
 vmadm create -f lx-noVNC.json
 zlogin <UUID>
 adduser human
@@ -378,11 +377,11 @@ exit
 zlogin -l human <UUID>
 git clone https://github.com/kanaka/noVNC.git
 cd noVNC/
-}}}
+```
 
 before starting it let's remind ourselves which LAN IPv4 address to bind to
 
-{{{
+```
   ip a
 
   1: lo: <LOOPBACK,MULTICAST,UP> mtu 8232 
@@ -393,17 +392,17 @@ before starting it let's remind ourselves which LAN IPv4 address to bind to
     link/ether 22:d5:0a:f1:06:83
     inet 10.0.0.8/24 scope site dynamic 
     inet6 fe80::20d5:aff:fef1:683/10 scope link dynamic 
-}}}
+```
 
 in a shell owned by ``human`` we run the client
-{{{
+```
   git clone https://github.com/kanaka/noVNC.git
   cd noVNC/
   ./utils/launch.sh --vnc 10.0.0.7:5901 --listen 6001
-}}}
+```
 
 that last command launches the web based vnc client and outputs like this
-{{{
+```
   Warning: could not find self.pem
   Using installed websockify at /usr/bin/websockify
   Starting webserver and WebSockets proxy on port 6080
@@ -420,37 +419,37 @@ that last command launches the web based vnc client and outputs like this
   http://72f04310-1615-ea7a-c415-d281550512bd:6080/vnc.html?host=72f04310-1615-ea7a-c415-d281550512bd&port=6080
 
   Press Ctrl-C to exit
-}}}
+```
 
 we must modify the above URL to this form
-{{{
+```
   http://<ONION>:6080/vnc.html?host=<ONION>&port=6080
-}}}
+```
 
 next we need to setup our tor onion service so that we know which onion address to replace <ONION> with.
 therefore we must login to our ``onion noVNC`` zone
-{{{
+```
   zlogin <UUID>
   cat /var/lib/tor/hidden_service/hostname
   ONION
-}}}
+```
 
 
 Previously we talked about the onion tor zone... you retrieve connecting information from that zone as previously described as
 utilize the onion address like this to fromulate a URL that connects to your sandbox!
-{{{
+```
   http://<ONION>:6080/vnc.html?host=<ONION>&port=6001
-}}}
+```
 
 Save this URL... we'll need it later after we've configured our VNC server.
 
 
-== setup Tor zone that TBB will use ==
+## setup Tor zone that TBB will use
 
 create the tor zone
 
 lx-client-tor.json:
-{{{
+```
 {
   "alias": "lx-client-tor",
   "brand": "lx",
@@ -468,23 +467,23 @@ lx-client-tor.json:
     }
   ]
 }
-}}}
+```
 
-{{{
+```
 vmadm create -f lx-client-tor.json
-}}}
+```
 
 login and install tor
 
-{{{
+```
   zlogin <UUID>
   apt-get update; update upgrade;
   apt-get install tor
-}}}
+```
 
 configure tor to listen on our LAN IPv4 address.
 list our interface addresses
-{{{
+```
   # ip a
   1: lo: <LOOPBACK,MULTICAST,UP> mtu 8232 
     link/loopback 00:00:00:00:00:00
@@ -494,27 +493,27 @@ list our interface addresses
     link/ether f2:93:94:f4:a4:40
     inet 10.0.0.12/24 scope site dynamic 
     inet6 fe80::f093:94ff:fef4:a440/10 scope link dynamic 
-}}}
+```
 
 then add the following line to ``/etc/tor/torrc``
-{{{
+```
 SocksPort 10.0.0.12:9050
-}}}
+```
 
 
 
-== setup Tor Browser zone ==
+## setup Tor Browser zone
 
 Actually, this zone could be used to sandbox any Linux or Solaris binaries.
 
 In this zone we'll run vnc4server along with the tor browser.
 This is so that tbb will simply be able to use the X server provided
-locally by vnc4server via the '''DISPLAY''' environment variable.
+locally by vnc4server via the **DISPLAY** environment variable.
 
 firstly we create the native linux zone, we login and upgrade
 
 lx-tbb-tor.json:
-{{{
+```
 {
   "alias": "lx-tbb",
   "brand": "lx",
@@ -532,31 +531,31 @@ lx-tbb-tor.json:
     }
   ]
 }
-}}}
+```
 
-{{{
+```
   vmadm create -f lx-tbb-tor.json
   zlogin <UUID>
   apt-get update; apt-get upgrade;
-}}}
+```
 
 setup vnc4server. first we install some dependencies
-{{{
+```
   apt-get install binutils libasound-dev libgtk2.0-dev libgtk-3-dev vnc4server fluxbox xterm
-}}}
+```
 
 set a vnc password
-{{{
+```
   vnc4passwd
-}}}
+```
 
 start the vnc server
-{{{
+```
   vnc4server :1
-}}}
+```
 
 here's my netstat output
-{{{
+```
   human@lx-tbb:~/tor-browser_en-US$ netstat -tlpn
   (Not all processes could be identified, non-owned process info
    will not be shown, you would have to be root to see it all.)
@@ -566,7 +565,7 @@ here's my netstat output
   tcp        0      0 0.0.0.0:6001            0.0.0.0:*               LISTEN      16503/Xvnc4     
   tcp6       0      0 :::22                   :::*                    LISTEN      -               
   tcp6       0      0 :::5901                 :::*                    LISTEN      16503/Xvnc4     
-}}}
+```
 
   
 setup tor browser with dtrace.
@@ -574,13 +573,13 @@ using the above information, the tor Socks address and port we can now configure
 tbb to use that tor instead of the default launched tor.
 
 login to the tbb zone and start tbb!
-{{{
+```
   zlogin -l human <UUID>
   TOR_SOCKS_HOST=10.0.0.12 TOR_SOCKS_PORT=9050 TOR_SKIP_LAUNCH=1 DISPLAY=:1 LX_DTRACE=1 ./start-tor-browser.desktop
-}}}
+```
 
 
-=== firewall the tor browser zone ===
+### firewall the tor browser zone
 
 the tor browser zone should not be able to access the Internet directly.
 it should only be able to access another zone's socks port where tor is running.
@@ -588,13 +587,13 @@ therefore we login to the firewall zone and add a firewall rule to block
 the tbb zone's access to the Internet.
 
 add these lines to ``/etc/ipf/ipf.conf``
-{{{
+```
   block out from 10.0.0.13/32
   block in from 10.0.0.13/32
-}}}
+```
 
 then activate the rules like this
-{{{
+```
   ipf -Fa -f /etc/ipf/ipf.conf
-}}}
+```