When launching privacy-critical apps and services, developers want to ensure that every packet really only goes through Tor. One mistyped proxy setting – or a single system-call outside the SOCKS wrapper – and your data is suddenly at risk. That's why we're excited to introduce oniux: a small command-line utility providing Tor network isolation for third-party applications using Linux namespaces.

Built on Arti, and onionmasq, oniux drops any Linux program into its own network namespace to route it through Tor and strips away the potential for data leaks. If your work, activism, or research demands rock-solid traffic isolation, oniux delivers it.

Namespaces are an isolation feature found in the Linux kernel that were introduced around 2000. They provide a secure way of isolating a certain part of an application from the rest of the system. Namespaces come in various forms and shapes, including network namespaces, mount namespaces, process namespaces, and more; each of them isolating a certain amount of system resources from an application.

In Linux, system resources are available globally by all applications on the system. The most notable example is probably your operating system clock, but there are many other areas as well, such as the list of all processes, the file system, and the list of users. Namespaces containerize a certain part of an application from the rest of the operating system; this is exactly what Docker uses to provide its isolation primitives.

We put each application in a network namespace that doesn't provide access to system-wide network interfaces (such as eth0), and instead provides a custom network interface onion0. This allows us to isolate an arbitrary application over Tor in the most secure way possible, software-wise, by relying on a security primitive offered by the operating system kernel.

Unlike SOCKS, the application cannot accidentally leak data by failing to make some connection via the configured SOCKS, which may happen due to a mistake by the developer. You may have also heard of a tool with a similar goal, known as torsocks, which works by overwriting all network-related libc functions in a way to route traffic over a SOCKS proxy offered by Tor.

While this approach is a bit more cross-platform, it has the notable downside that applications making system calls not through a dynamically linked libc, either with malicious intent or not, will leak data. Most notably, this excludes support for purely static binaries and applications from the Zig ecosystem.

How to use oniux?

First, you need a Linux system with a Rust toolchain installed. Afterwards, you can install oniux with the following command:

cargo install oniux

Once that is done, you're ready to go for using oniux!

How does oniux work internally?

oniux works by immediately spawning a child process using the clone(2) system call, which is isolated in its own network, mount, PID, and user namespace.

This process then mounts its own copy of /proc followed by UID and GID mappings to the respective UID and GID of the parent process. Afterwards, it creates a temporary file with nameserver entries that will then be bind-mounted onto /etc/resolv.conf, so that applications running within will use a custom name resolver that supports resolving through Tor.

Next, the child process utilizes onionmasq to create a TUN interface named onion0 followed by some rtnetlink(7) operations required to set up the interface, such as assigning IP addresses. Then, the child process sends the file descriptor of the TUN interface over a Unix Domain socket to the parent process, who has been waiting for this message ever since executing the initial clone(2).

Once that is done, the child process terminates.

We want to thank the developers of smoltcp, which is a Rust crate that implements a full IP stack in Rust – something we make heavy use of. We also want to thank 7ppKb5bW for teaching us how this can be implemented without the use of capabilities(7) by using user_namespaces(7) properly.

Last but not least, many thanks go to all people and organizations who support Tor financially. The Tor Project, Inc. is a 501(c)(3) nonprofit advancing human rights and defending privacy online through free software and open networks. The oniux release is powered by a community of supporters. Please consider donating today to continue advancing our work that makes privacy possible.