From Gentoo Wiki
Jump to: navigation, search


xombrero is a minimalistic web browser striving to be compact, secure, and fast.


The principal difference between xombrero and other full-featured browsers is that the sophisticated security features are designed in, rather than added through an add-on after-the-fact. With a strong accent on staying out of the way, it doesn't decide for you what search engine you want to use or what certificate authority you want to trust. Heavy vim users will also find its vim-like keybindings convenient, as it is easy to surf the web completely from keyboard.


USE flags

Cannot load package information. Is the atom www-client/xombrero correct?


Install www-client/xombrero:

root #emerge --ask www-client/xombrero


The configuration file is named ~/.xombrero.conf and located in the home directory by default. Starting xombrero with the command-line parameter -f, one can select a different configuration file, located anywhere on the system. This is convenient for separating different browsing activities, e.q. browsing with or without Tor, or accessing a bank account with a browser configured to accept cookies and run javascript, and surfing the web with a more secure configuration. The browser can be started like so:

user $xombrero -f .xombrero.conf
user $xombrero -f .torbrowser.conf

To simplify configuration xombrero allows to choose between two high-level modes of browsing: browser_mode and gui_mode. Each mode represents a number of low-level settings.

browser_mode and gui_mode MUST be the first entries in the configuration file!

Browser mode

Most users should use browser_mode and shouldn't tweak low-level settings manually unless they know what they are doing. There are two modes: normal and whitelist. Each of this modes and the settings they enable are listed below:

The settings for 'browser_mode=normal' are as follows:

FILE ~/.xombrero.confSettings enabled by the browser_mode=normal high-level setting
# allow_volatile_cookies        = 0
# cookie_policy                 = allow
# cookies_enabled               = 1
# enable_cookie_whitelist       = 0
# read_only_cookies             = 0
# save_rejected_cookies         = 0
# session_timeout               = 3600
# enable_scripts                = 1
# enable_js_whitelist           = 0
# enable_localstorage           = 1
# enable_plugins                = 1
# enable_plugin_whitelist       = 0
# allow_insecure_content        = 1
# allow_insecure_scripts        = 1
# do_not_track                  = 0

The settings for 'browser_mode = whitelist' are as follows:

FILE ~/.xombrero.confSettings enabled by the browser_mode=whitelist high-level setting
# allow_volatile_cookies        = 0
# cookie_policy                 = no3rdparty
# cookies_enabled               = 1
# enable_cookie_whitelist       = 1
# read_only_cookies             = 0
# save_rejected_cookies         = 0
# session_timeout               = 3600
# enable_scripts                = 0
# enable_js_whitelist           = 1
# enable_localstorage           = 0
# enable_plugins                = 0
# enable_plugin_whitelist       = 1
# allow_insecure_content        = 0
# allow_insecure_scripts        = 0
# do_not_track                  = 1

Of course, these settings can be overridden later in the xombrero configuration file. See the xombrero man page for a more detailed explanation of each of them. Also, a good explanation on how to configure the settings is given in the file /usr/share/doc/xombrero-*/examples/xombrero.conf.bz2 if the examples USE flag was enabled. The :set command can be used in order to view the enabled settings.

GUI mode

The browser's appearance can be adjusted to your likes by setting two high-level gui modes: classic (the default) and minimal. In the classic mode the browser looks like the most modern web browsers. The minimal mode is similar to the vi interface. The following low-level GUI settings are set by the high-level "gui-mode".

The settings for 'gui_mode = classic' are as follows:

FILE ~/.xombrero.confSettings enabled by the gui_mode=classic high-level setting
# fancy_bar             = 1
# show_tabs             = 1
# tab_style             = normal
# userstyle_global      = 0
# show_url              = 1
# show_statusbar        = 0
# show_scrollbars       = 1

The settings for 'gui_mode = minimal' are as follows:

FILE ~/.xombrero.confSettings enabled by the gui_mode=minimal high-level setting
# fancy_bar             = 0
# show_tabs             = 1
# tab_style             = compact
# show_url              = 0
# show_statusbar        = 1
# show_scrollbars       = 0

For more information, please see /usr/share/doc/xombrero-*/examples/xombrero.conf.bz2.


In addition to the browser modes listed above, there is also a number of other parameters, which can be set in .xombrero.conf. Examples of them are:

FILE ~/.xombrero.confExamples of other settings
# Cookie whitelist
cookie_wl	= wiki.gentoo.org
# Javascript whitelist
js_wl		= wiki.gentoo.org
# Set your favorite editor to edit currently active input-element with the C-i command;
# (it works on editing gentoo wiki articles too, for example it was very easy to adjust these settings with tabs using vim)
external_editor	= urxvt -e vim <file>
# xombrero can be easily used with mitmproxy or any other proxy required
http_proxy	=
# Referer can be set to one the following values: always, never, same-domain, same-fqdn or any valid URL
referer		= same-domain
# Examples of keybindings
keybinding	= tabnew,t
keybinding	= focusaddress,!C-l
keybinding	= tabnext,!C-period
keybinding	= tabprevious,!C-comma
keybinding	= command_mode,!C-bracketleft
# Search settings, can be safely omitted, as xombrero asks what search engine you prefer on the first search;
# however, these examples are quite convenient
search_string	= https://startpage.com/do/m/mobilesearch?language=english&cat=web&query=%s
guess_search	= 1
# Type "d word" to search a word in a dictionary
alias		= d,http://thefreedictionary.com/%s
# Set the work directory where all xombrero scratch files are stored
work_dir	= ~/.xombrero

Managing SSL Certificates

Validating SSL Certificates is possible in at least two ways. Each of them depends on how much trust one puts in the certificate authority.

CA Certificate Files

This approach uses CA certificate files, which are stored in the /etc/ssl/certs/ directory. As WebKit only supports a single PEM file, one can simply concatenate all separate files into a single one with the following command:

user $cd /etc/ssl/certs/ && for i in `ls`; do cat $i >> ~/.xombrero/cert.pem; done

Then edit .xombrero.conf and add there this line:

FILE ~/.xombrero.conf
ssl_ca_file	= /home/user/.xombrero/cert.pem

The URL bar of the visited site will be colored green when the certificate is trusted. It will be colored yellow when the certificate is untrusted. The blue color signifies that the certificate was saved earlier in the ~/.xombrero/certs directory.

It is recommended to periodically recreate the cert.pem file.

Tor-based Approach

Due to a number of accidents where CA certificates were compromised and used in a man-in-the-middle attack, and as attackers not always alert the users that a well-done compromise has taken place, it makes sense to opt for another model of certificate validation. The approach is based on the assumption that the attacker cannot successfully compromise all nodes in the network and cannot always send tampered SSL certificates through different encrypted network routes. The following steps need to be taken:

1. Access a site using a non-torified browser;

2. Save the site's SSL certificate into ~/.xombrero/certs with the :cert save command;

3. Next time the site is accessed, the URL bar will be colored blue. It shows that the SSL certificate sent by the site doesn't differ from the one saved in the local store;

4. Access the same site using a torified browser. If the color is still blue, it means that the certificate is valid. Access the site again using different Tor circuits and exit nodes. In all cases, the URL bar color must still be blue (except when you've got a tampered SSL certificate sent by a rogue exit node);

5. If the color is yellow, or red at any step, it means that the certificate is tampered. If the site sends the same certificate through different Tor circuits, and this certificate is still different from the one gotten at the very first step, it could probably mean that the internet connection was modified at some point. The more exit nodes send you the same certificate, the higher this probability is.

None of the steps described above needs a certificate authority one must put all trust in.

Running Scripts

The user can run custom scripts on webpages with the run_script command. Let's consider as example the following script for watching videos from youtube and other sites supported by youtube-dl. Let it be located in the home directory and called youtube_watch.sh like so:

FILE ~/youtube_watch.shCustom script to watch videos from youtube and other sites
mplayer -vo x11 -fs `youtube-dl --skip-download -g $1`

Then, the script can be called with the :run_script ~/youtube_watch.sh command. To simplify it, these lines can be added to ~/.xombrero.conf:

FILE ~/.xombrero.conf
cmd_alias	= yt,run_script ~/youtube_watch.sh

Changing Default CSS

The browser allows to toggle the page style between the default cascading style sheet and a low-contrast color scheme. The stylesheet can be changed for the opened web pages by pressing the s key to do it just for the current tab, or S to change it for all tabs. It is also possible to add the userstyle and userstyle_global settings to the browser configuration file and provide the custom stylesheet, changing the overall look and feel of opened web pages.