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
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.
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.
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.
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.
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
- 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
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:
- Use the f key to tag the visible links with numbers. Follow a link by typing its number.
- :cookiejar to see the cookies currently saved on your machine.
- :cookie save to allow the site to save cookies on your machine.
- :js save to allow scripts on this page to run.
- :ca to see the certificate authorities
- :cert to see the certificates for this site.
- :cert save to save the certificates for this site.
- 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.)
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.
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)
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)
These commands allow the user to map specific actions to specific keys. It can be useful when the -S option is used.
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 (reloadforce) 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.
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.
These commands copy and paste text to and from the clipboard.
p Paste the contents of the clipboard into the address bar (pasteuricur) P Paste the contents of the clipboard into a new tab (pasteurinew) y Yank the current URL into the clipboard (yankuri)
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. (hinting) , (comma), F Highlight all links and prefix them with a number. (hinting_newtab)
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)
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)
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 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 domain.
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 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 session_name.
stats Show blocked cookie statistics. These statistics vary based on settings and are not persistent.
statustoggle, statust Toggle status bar.
stop 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.
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 &
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.
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.
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://127.0.0.1:9050/
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
# 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
Add both daemons to /etc/rc.conf.local so that they will be started upon reboot
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 = http://127.0.0.1:8123/
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:
sudo make install
- Bug tracker
- Mailing lists
- xombrero (discussion)
- subscribe: email xombrero+subscribe at opensource.conformal.com
- unsubscribe: email xombrero+unsubscribe at opensource.conformal.com
- subscribe: email xombrero-commits+subscribe at opensource.conformal.com
- unsubscribe: email xombrero-commits+unsubscribe at opensource.conformal.com
- xombrero (discussion)
- Anonymous source is available via one of the following:
- git clone git://opensource.conformal.com/xombrero.git
- git clone https://opensource.conformal.com/git/xombrero.git
- If you'd like to read a short rationale as to why it was written please visit this link.
Additional build and installation information for Linux can be found here.
/* * Copyright (c) 2010, 2011 Marco Peereboom <firstname.lastname@example.org> * Copyright (c) 2011 Stevan Andjelkovic <email@example.com> * Copyright (c) 2010, 2011 Edd Barrett <firstname.lastname@example.org> * Copyright (c) 2011 Todd T. Fries <email@example.com> * Copyright (c) 2011 Raphael Graf <firstname.lastname@example.org> * Copyright (c) 2011 Michal Mazurek <email@example.com> * Copyright (c) 2012, 2013 Josh Rickmar <firstname.lastname@example.org> * Copyright (c) 2013 David Hill <email@example.com> * * 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. * * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. */
/* 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. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. */
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 <firstname.lastname@example.org>. // Portions created by the Initial Developer are Copyright (C) 2007 // the Initial Developer. All Rights Reserved. // // Contributor(s): // Ruben Arakelyan <email@example.com> // Gervase Markham <firstname.lastname@example.org> // Pamela Greene <email@example.com> // David Triendl <firstname.lastname@example.org> // Jothan Frakes <email@example.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 *****