John C. Vernaleo edited this page Aug 26, 2015 · 8 revisions
Clone this wiki locally

xombrero is a minimalist web browser with sophisticated security features designed-in, rather than through an add-on after-the-fact. In particular, it provides both persistent and per-session controls for scripts and cookies, making it easy to thwart tracking and scripting attacks.

In additional to providing a familiar mouse-based interface like other web browsers, it offers a set of vi-like keyboard commands for users who prefer to keep their hands on their keyboard.

The default settings provide a secure environment. With simple keyboard commands, the user can "whitelist" specific sites, allowing cookies and scripts from those sites.

It is ISC licensed.

We have a public BETA for the Windows port of xombrero! More information on this page

Table of Contents

Browse Securely

Web browsing exposes you and your computer to numerous threats. Two of the largest threats are the privacy threat of web tracking and the security threat of malicious scripts. xombrero is designed to give you explicit control over the features exploited by those threats.

Web Tracking

Browse more securely by controlling which sites are allowed to set cookies on your computer.

Many websites track users. This is often innocuous, with sites tracking users simply to provide a consistent user experience, such as by preserving settings from one session to another. Others track users more broadly and for more intrusive reasons, e.g. tracking across multiple sites to identify patterns of interest to present more profitable advertising. If you occasionally click on ads, you will quickly accumulate hundreds of cookies with information about your supposed interests. The result will be more ads targeted to those interests. The high value that advertisers place on this information prompts them to go to considerable effort to thwart any attempt to delete the tracking information.

The most important way web sites track users is with cookies—small pieces of information saved on your computer and passed back to the site on future visits.

Since there are valid reasons for sites to track their users, xombrero provides the functionality to whitelist a particular site, allowing it to set cookies. In some cases this is merely convenient—allowing a blog to provide a comment form with the name, email address, and URL fields already filled in. Other times it is essential for the functioning of the website—allowing the site to associate related requests with a session ID.

If you use a site routinely, you may want to permanently whitelist the site (:cookie save). If you don’t expect to use the site again (or not for a long time), you can add it to the per-session whitelist. This will allow you to take advantage of the functionality enabled by the cookies, without exposing you to tracking of your browsing habits beyond this session. If you don’t need the functionality enabled by the cookies, you need not take any action.

In some cases websites track visitors to their site using DNS by embedding large numbers of hostnames in their pages that require a DNS lookup. Almost every browser has DNS prefetch enabled by default, meaning that upon loading a new page all of the hostnames referenced in the page are looked up using DNS whether a visitor follows the links or not. At many sites this means doing hundreds of DNS lookups per page loaded, with most of them returning NX responses. Similarly, many browsers perform full link prefetching by default, which is downloading the content of all the embedded links, not just looking up their DNS. xombrero has both DNS and link prefetching disabled by default since these operations can be used to track users.

Scripting Attacks

Browse securely by controlling which sites are allowed to run scripts on your computer.

Many websites use scripts to provide functionality that would be slow or difficult to provide from the server. Modern web browsers attempt to limit the opportunity for those scripts to do harm, but there have been many instances of malicious scripts—including some cross-site scripting (XSS) attacks, where scripts from one site, such as a game site, make improper use of the user's credentials on another site, such as a bank site.

So you can use the features enabled by scripts, xombrero provides the functionality to whitelist specific sites, allowing its scripts to run on your machine.

If you use a site routinely, you may want to permanently whitelist the site (:js save). If you don’t expect to use the site again (or not for a long time), you can add it to the per-session whitelist. This will allow you to take advantage of the functionality enabled by the scripts, while limiting your exposure to malicious scripts to just this browsing session. If you don’t need the functionality provided by the scripts, you need not take any action.

Dealing with Other Dangers

A fundamental design principle of xombrero is to put the user in charge of his or her own security decisions.

For example, instead of deciding for you which certificate authorities are trusted, xombrero puts the user in control. If you save a site's certificate, xombrero will check it on all future visits, and present a visual indication if it matches.

Part of this is designing the tool to make it easy to avoid some common mistakes. In particular, xombrero does not have the "feature" of treating a non-URL in the URL field as if it were a search string. This keeps the common mistake of accidentally pasting a password into the URL field from resulting in sending your password to the search engines.


For details on how to enable and use the whitelist functionality, see the command mode section. The commands for controlling the cookie and script whitelists are the “cookie” and “js” commands. The "ca" and "cert" commands give you control over certificate authorities and certificates.

For more information on the kinds of threats that led to the creation of xombrero, see the XXXTerm rationale page.

Major Features

The major features of xombrero are:

  • Tabbed browsing
  • Written entirely in C
  • Based on Webkit and GTK3, with GTK2 compatibility
  • Built with security in mind
  • Minimal on-screen layout
  • Cookie, javascript and plugin toggles and whitelists
  • Browsing session data auto-saves in case of crash
  • Simple integration with Tor and other web proxies
  • vi-like default keybindings
  • Mouse-less browsing
  • Basic MIME support
  • Seamless upgrade process
  • DNS and link prefetch disabled by default
  • Colorful address bar indicates HTTPS certificate status
  • Control over user_agent presented to sites
  • Download manager
  • Text-based config file
  • Bookmarks, i.e. favorites
  • Printing, including to PDF

Quick-Start Tutorial

You use xombrero the same way you use any other browser. This section provides a quick introduction to its unique features.

Browse to a few familiar webpages (including some secure webpages) and try these experiments:

  1. Use the f key to tag the visible links with numbers. Follow a link by typing its number.
  2. :cookiejar to see the cookies currently saved on your machine.
  3. :cookie save to allow the site to save cookies on your machine.
  4. :js save to allow scripts on this page to run.
  5. :ca to see the certificate authorities
  6. :cert to see the certificates for this site.
  7. :cert save to save the certificates for this site.
  8. Leave and return to the site. Observe that the address bar is blue. (If you visit the site and it offers a different certificate, the address bar will be red.)
Many sites that used to use https only for login pages now allow all traffic to pass over https. If you routinely direct your browsing over https, you can keep your browsing activity private, while at the same time ensuring that you're actually talking to the site you intend to.


This section describes some of the more common keyboard commands. As described at the end of this section, the key bindings can be changed as desired. For an exhaustive list of keyboard commands please refer to the manual page. Many default vi keybindings are used for analogous actions when issuing keyboard commands in xombrero.

To browse to a specific address, either use the mouse to click on the address bar or press F6 to shift the keyboard focus to the address bar, then enter the address manually.

The mouse can be used to navigate the page in the traditional manner, or the keyboard can be used. (For example, PageUp and PageDown will scroll up and down the page.)

To follow a link, either click on it or use the f key and have xombrero assign numbers to each link on the page; entering that number on the keyboard will prompt xombrero to follow the link.

Search Commands

These commands are used to search for text strings within a web page.

           /       Start a search (search)
           ?       Start a backwards search (searchb)
           n       Next item matching search (searchnext)
           N       Previous item matching search (searchprev)

Focus Commands

These commands are used to shift the focus of xombrero from one area to another.

           Esc     Remove focus
           i       Focus on default page input
           F6      Focus on address bar (focusaddress)
           F7      Focus on search entry (focussearch)

Command Aliases

These commands allow the user to map specific actions to specific keys. It can be useful when the -S option is used.

Navigation Commands

These commands allow the user to navigate web pages, and to some extent, control the browser.

           F5, C-r, C-l             Reload page (reload)
           C-R                      Reload page without using any cached data
           Backspace, M-Left        Previous page (goback)
           S-BackSpace, M-Right     Forward page (goforward)
           j, Down                  Next line on page (scrolldown)
           k, Up                    Previous line on page (scrollup)
           Space, C-f, PageDown     Page down (scrollpagedown)
           C-b, PageUp              Page up (scrollpageup)
           M-f                      Favorites (fav)
           M-j                      Cookie jar (cookiejar)
           M-d                      Download manager (dl)
           C-p                      Print page (print)
           M-h                      Global history (history)
           M-r                      Run script (run_script)
           C-j                      Toggle Java Script enabled for FQDN (js)
           C-s                      Toggle source view (togglesrc)
           M-c                      Toggle cookie enabled for FQDN (cookie)
           F4                       Toggle cookie, Java Script and plugins enabled for FQDN

M-f for show favorites will be executed even if the focus is in the address bar or the search entry box.

Tab Manipulation

xombrero supports tabbed browsing. That is, web pages may be opened in separate tabs, allowing the user to quickly move from one page to another, and back. These commands then are used to create, destroy, and move between tabs.

           MB3,C-MB1           Open new tab with the clicked link
           C-t                 Create new tab with focus in URL entry (tabnew)
           C-w                 Destroy current tab (tabclose)
           U                   Undo close tab (tabundoclose)
           C-Left              Go to the previous tab (tabprevious)
           C-Right             Go to the next tab (tabnext)
           C-<                 Jump to first tab (tabfirst)
           C->                 Jump to last tab (tablast)
           C-n                 Status toggle (statustoggle)

C-w for destroy current tab will be executed even if the focus is in the address bar or the search entry box.

Yanking and pasting

These commands copy and paste text to and from the clipboard.

           p       Paste the contents of the clipboard into the address bar
           P       Paste the contents of the clipboard into a new tab
           y       Yank the current URL into the clipboard (yankuri)

Hyperlink Following

This allows the user to follow hyperlinks without using a mouse. Enter the corresponding number to follow the link. Alternatively, one can type the name of the link and when there are no more possibilities xombrero will follow the link.

           . (dot), f       Highlight all links and prefix them with a number.
           , (comma), F     Highlight all links and prefix them with a number. 

If the link is highlighted with . (dot) or f, entering the corresponding number will follow the link in the same tab. If the link is highlighted with , (comma) or F, entering the corresponding number will follow the link in a new tab.


Commands to exit the browser.

           M-q     Restart current xombrero process from binary on disk (restart) 
           C-q     Quit (quitall)

Low-Contrast Color Scheme

This command toggles the page's style between the default CSS and a low-contrast color scheme with light grey text on a dark grey background.

           s       Toggle the current tab's style.  (userstyle)

Key Bindings

Most of the key bindings listed above can be reprogrammed using a keybinding entry in the configuration file.

Each keyboard shortcut requires exactly one entry in the configuration file. A shortcut can have multiple entries in the configuration file. The format of the keybinding entry is as follows:

           keybinding = action,(!)keystroke(s)

For example, keybinding = tabnew,C-t where tabnew is the action and C-t are the keystrokes. GTK has some default keybindings for manipulating text inside input fields, such as the URI or search entry widget, for example C-w deletes a word. To override these defaults prefix your key with an exclamation mark, like this: keybinding = tabclose,!C-w. The clearall key word is special and is meant to reset the key binding list to the GTK+ and WebKit defaults. This keyword should be the first keybinding entry in the configuration file.

Shift should be used sparingly since it gets in the way of non-USA keyboards. See the accompanying configuration file for examples.

Command Mode

Command mode works in a similar fashion to the vi(1) editor; it is entered by typing a colon and exited by typing Esc. Common commands and their descriptions are listed below. Please refer to the manual page for a complete list of commands.

           cert, cert show
                   Download and display certificates of domain on tab.
           cert save
                   Save certificate into a local store.  The next time the
                   site is visited it is compared against the store.  If the
                   certificate matches, the address bar will be blue; if it
                   doesn't the bar will be red.
           cookie  The cookie command is used to manipulate the cookie
                   whitelist.  Used by itself it expands to cookie show all.
           cookie save domain
                   Save the top level domain name to the persistent whitelist.
                   For example, the www.peereboom.us domain would result in
                   saving .peereboom.us. (This action enables cookies if it is 
                   currently disabled for this entry.)
           cookie toggle domain
                   Toggle cookie support for the current top level domain.
           dl      Show download manager.
           fav     Show favorites.
           favadd  Add the current page to favorites.
           fullscreen, f
                   Toggle hiding tabs and url entry toolbar.
           h, hist, history
                   Show global history.
           help    Show help page.
           home    Go to home URL.
           js      The js command is used to manipulate the Java Script
                   whitelist.  Used by itself it expands to js show all.
           js save domain
                   Saves the top level domain name to the persistent
                   whitelist.  For example, the www.peereboom.us domain would
                   result in saving .peereboom.us. (This action enables Java 
                   Script if it is currently disabled for this entry.)
           js toggle domain
                   Toggle Java Script execution for the current top level
           open, op, o URL
                   Open URL.
           plugin  The plugin command is used to manipulate the plugin
                   whitelist.  Used by itself it expands to plugin show all.
           plugin save domain
                   Save the top level domain name to the persistent whitelist.
                   For example, the www.peereboom.us domain would result in
                   saving .peereboom.us. (This action enables plugins if it is 
                   currently disabled for this entry.)
           plugin toggle domain
                   Toggle plugin support for the current top level domain.
           print   Print page.
           qa, qall, quitall
                   Quit xombrero.
           quit, q
                   Close current tab and quit xombrero if it is the last tab.
                   Restart xombrero and reload all current tabs.
           run_script [path_to_script]
                   Runs the script path_to_script with the current uri as the
                   argument.  If path_to_script is not provided, the value of
                   default_script is used instead.
           session, session show
                   Display the current session name.  By default the session
                   name is main_session.  To create a new session use the
                   session save command.  A session is defined as the lifetime
                   of the browser application.
           session delete <session_name>
                   Delete session session_name from persistent storage.  If
                   session_name is the current session then the session will
                   revert to main_session.
           session open <session_name>
                   Open session_name and close all currently open tabs.  Going
                   forward this session is named session_name.
           session save <session_name>
                   Save current tabs to session_name session.  This will close
                   the current session and going forward this session is named
           stats   Show blocked cookie statistics.  These statistics vary
                   based on settings and are not persistent.
           statustoggle, statust
                   Toggle status bar.
                   Stop loading of page in current tab.
           toplevel, toplevel toggle
                   Toggle the top level domain name cookie and JS session
                   whitelist.  This is to enable/disable short lived full site
                   functionality without permanently adding the top level
                   domain to the persistent whitelist.
           w       Save open tabs to current session.  The tabs will be
                   restored next time the session is opened.  See the session
                   command for additional details.
           wq      Save open tabs and quit.  The tabs will be restored next
                   time xombrero the session is opened.  See the session
                   command for additional details.

Most users should use the commands above for controlling the whitelists. For advanced users, the whitelists section describes an interface for controlling internal details of their operation.


This section describes advanced usage settings. To run xombrero with whitelists the .xombrero.conf file must have browser_mode = whitelist.

xombrero has several whitelists to control cookies, Java Script and plugins for FQDNs or domains. When properly enabled these whitelists require either the FQDN or top level domain to exist in the whitelists in order to allow cookies to be stored or Java Script and plugins to execute. Java Script, plugins and cookies each have two whitelists associated with them: session and persistent. Items in the session whitelists are only allowed for the lifetime of the xombrero instance. Items in the persistent whitelists are stored on disk and are restored upon restart.

For details on viewing and controlling the whitelists, see the "cookie", "js" and "plugin" commands in the command mode section and the manual page.


Ensuring continuity of the browsing experience means keeping track of potentially large numbers of tabs and, in some cases, doing so across multiple xombrero processes. xombrero tracks and manages tabs using "sessions", where a session is taken to mean a collection of tabs in a given xombrero process. One can save, open, delete and show a session by name, e.g. issue the command :session save testpress to save the current tabs open into a session named testpress. Upon starting a xombrero process, it is possible to have it open a named session

 xombrero -s testpress &

and this will restore the tabs saved when issuing the command :session save testpress earlier.

By setting session_autosave = 1 in .xombrero.conf new activity in a given session is saved to a file in .xombrero/sessions/. An autosaved session is very helpful in the context of crashes, OS restarts or process restarts since it can be very irritating to lose tabs that were in use before xombrero terminated. Restoring multiple sessions can be performed as follows

 xombrero -s session1 &
 xombrero -s session2 &
 xombrero -s session3 & 

Buffer Commands

In addition to shortcuts and commands xombrero provides buffer commands. Buffer commands are short, multi character vi-like commands, often requiring an argument. Partial buffer commands are displayed in the buffer command statusbar element (see statusbar_elems). Pressing Esc or switching to another tab cancels a partially entered buffer command. In the following list arg denotes the argument a buffer command accepts. Buffer commands are defined as extended regular expressions. Note that if a character is used as a shortcut it will not be interpreted as the beginning of a buffer command. This is the case with 0.

           gg                  go to the top of the page
           gG                  go to the bottom of the page
           [0-9]+%             go to the arg percent of the page
           m[a-zA-Z0-9]        set a mark denoted by arg at the current page
                               position. These marks behave like those in vi
                               or less.
           [`'][a-zA-Z0-9]     go to the position where mark arg was set
           [0-9]+t             activate tab number arg
           [0-9]+Z             set zoom level to arg %

For a full list of the buffer commands, refer to the manual page.


Quickmarks are like bookmarks, except they are referred to by a single character (a letter or a digit), instead of a longer name. See the M[a-zA-Z0-9], go[a-zA-Z0-9] and gn[a-zA-Z0-9] buffer commands for usage. Quickmarks are stored in ~/.xombrero/quickmarks and are saved automatically after each M[a-zA-Z0-9] buffer command.

Command Line Options

A few key options are as follows:

Open a new tab in a running xombrero for each specified URL. This option requires enable_socket to be enabled.
-e command
Execute arbitrary command (see the #Command Mode section) in a running xombrero instance. This option requires enable_socket to be enabled. Example run:
 xombrero -e "tabnew openbsd.org"; xombrero -e tabclose; xombrero -e wq.
-s session_name
Open session that was saved with ":session save" command.
Disable visualization of tabs.
Disable tabs.
Display version and exit.
Refer to the manual page for a full listing of the command line options.

Anonymous browsing using Tor

xombrero depends on libsoup to provide proxy support. If using xombrero 1.6.0 or newer with libsoup 2.42.2 or newer, a Tor connection can be established directly using a SOCKS proxy. If either of these version requirements are not met, a locally running HTTP proxy capable of working with Tor (such as polipo) is necessary.

A xombrero.conf example using socks5 directly:

http_proxy = socks5://

Otherwise, the OS independent steps are:

  • Install an HTTP proxy that can be combined with Tor such as polipo.
  • Install the Tor daemon.
  • Configure polipo to use Tor; our friends at Tor provide a handy configuration file to simplify this process.
  • Configure Tor to run as a daemon.
  • Set http_proxy in .xombrero.conf
As an example we'll get xombrero to run with Tor on an OpenBSD machine.
# pkg_add polipo
# pkg_add tor

Add the following lines to /etc/polipo/config

daemonise = true
logSyslog = true
socksParentProxy = "localhost:9050"
socksProxyType = socks5

Make sure /etc/tor/torrc has the following line

RunAsDaemon 1

Add both daemons to /etc/rc.conf.local so that they will be started upon reboot

pkg_scripts="tor polipo"

To manually start the daemons simply type

# sh /etc/rc.d/tor start
# sh /etc/rc.d/polipo start

Add the local Tor proxy to ~/.xombrero.conf

http_proxy =

Note that Tor has some side effects due to traffic being redirected all over the world. For example one might end up with a different language on a website because traffic came in on an IP address from another country. Some sites do not work at all with Tor. There is a bit of a slowdown to be expected when surfing using Tor. That said, if one cherishes their privacy this is an invaluable tool that comes with a bit of sacrifice.


Currently xombrero can only be built on OSX for X11 although a native port is in progress.

Other than dependencies, the build goes very much the same way as it does on Linux.

OSX 10.7 comes with X11 installed by default. On 10.8 and later, you will need to manually install X11. It is available at:


For the remaining dependencies, you should probably use a package manager such as MacPorts or Homebrew. MacPorts has been tested more extensively, but we have reports of Homebrew working as well.

With macports, install the required dependancies:

     sudo port install libsoup webkit-gtk3 xorg-libX11

It is possible to build against webkit-gtk (the GTK2 version of webkit), but that is not recommended.

Checkout the xombrero code from git:

     git clone https://github.com/conformal/xombrero.git

Change to the proper directory:

     cd xombrero/osx



And install:

     sudo make install

xombrero resources

  • Forum
  • Bug tracker
  • viewgit
  • manpage
  • Snapshots
  • Mailing lists
    • xombrero (discussion)
      • subscribe: email xombrero+subscribe at opensource.conformal.com
      • unsubscribe: email xombrero+unsubscribe at opensource.conformal.com
    • xombrero-commits
      • subscribe: email xombrero-commits+subscribe at opensource.conformal.com
      • unsubscribe: email xombrero-commits+unsubscribe at opensource.conformal.com
  • Anonymous source is available via one of the following:
  • If you'd like to read a short rationale as to why it was written please visit this link.
xombrero is based on webkit using GTK+.

Additional build and installation information for Linux can be found here.


 * Copyright (c) 2010, 2011 Marco Peereboom <marco@peereboom.us>
 * Copyright (c) 2011 Stevan Andjelkovic <stevan@student.chalmers.se>
 * Copyright (c) 2010, 2011 Edd Barrett <vext01@gmail.com>
 * Copyright (c) 2011 Todd T. Fries <todd@fries.net>
 * Copyright (c) 2011 Raphael Graf <r@undefined.ch>
 * Copyright (c) 2011 Michal Mazurek <akfaew@jasminek.net>
 * Copyright (c) 2012, 2013 Josh Rickmar <jrick@devio.us>
 * Copyright (c) 2013 David Hill <dhill@mindcry.org>
 * Permission to use, copy, modify, and distribute this software for any
 * purpose with or without fee is hereby granted, provided that the above
 * copyright notice and this permission notice appear in all copies.

javascript.h license

Javascript code was borrowed from the friendly folks at vimprobable2 under the following license:

Copyright (c) 2009 Leon Winter
Copyright (c) 2009-2011 Hannes Schueller
Copyright (c) 2009-2010 Matto Fransen
Copyright (c) 2010-2011 Hans-Peter Deifel
Copyright (c) 2010-2011 Thomas Adam
Copyright (c) 2011 Albert Kim
Copyright (c) 2011 Daniel Carl

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.


tld-rules license

The whitelist code relies on an external file to detect non-standard domain names such as news.bbc.co.uk. This list is licensed as follows:

// ***** BEGIN LICENSE BLOCK *****
// Version: MPL 1.1/GPL 2.0/LGPL 2.1
// The contents of this file are subject to the Mozilla Public License Version 
// 1.1 (the "License"); you may not use this file except in compliance with 
// the License. You may obtain a copy of the License at 
// http://www.mozilla.org/MPL/
// Software distributed under the License is distributed on an "AS IS" basis,
// WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
// for the specific language governing rights and limitations under the
// License.
// The Original Code is the Public Suffix List.
// The Initial Developer of the Original Code is
// Jo Hermans <jo.hermans@gmail.com>.
// Portions created by the Initial Developer are Copyright (C) 2007
// the Initial Developer. All Rights Reserved.
// Contributor(s):
//   Ruben Arakelyan <ruben@rubenarakelyan.com>
//   Gervase Markham <gerv@gerv.net>
//   Pamela Greene <pamg.bugs@gmail.com>
//   David Triendl <david@triendl.name>
//   Jothan Frakes <jothan@gmail.com>
//   The kind representatives of many TLD registries
// Alternatively, the contents of this file may be used under the terms of
// either the GNU General Public License Version 2 or later (the "GPL"), or
// the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
// in which case the provisions of the GPL or the LGPL are applicable instead
// of those above. If you wish to allow use of your version of this file only
// under the terms of either the GPL or the LGPL, and not to allow others to
// use your version of this file under the terms of the MPL, indicate your
// decision by deleting the provisions above and replace them with the notice
// and other provisions required by the GPL or the LGPL. If you do not delete
// the provisions above, a recipient may use your version of this file under
// the terms of any one of the MPL, the GPL or the LGPL.
// ***** END LICENSE BLOCK *****

style.css license

The low-contract CSS was taken from userstyles.org and is released under a CC BY-SA license.