https://github.com/debfx/runjail
ad-hoc sandboxes on Linux
https://github.com/debfx/runjail
linux sandbox seccomp security
Last synced: 5 months ago
JSON representation
ad-hoc sandboxes on Linux
- Host: GitHub
- URL: https://github.com/debfx/runjail
- Owner: debfx
- License: gpl-3.0
- Created: 2020-07-04T17:41:20.000Z (almost 6 years ago)
- Default Branch: main
- Last Pushed: 2025-12-01T18:01:55.000Z (7 months ago)
- Last Synced: 2025-12-04T07:52:14.732Z (7 months ago)
- Topics: linux, sandbox, seccomp, security
- Language: Go
- Homepage:
- Size: 225 KB
- Stars: 19
- Watchers: 2
- Forks: 3
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# runjail
runjail is a tool to create ad-hoc sandboxes on Linux.
It is intended to restrict access of the applications inside the sandbox
to your system but not to provide a completely different runtime environment
like Docker or Flatpak does.
A common use case might be quickly testing a new tool you just discovered
without allowing it access to all your data.
`runjail --rw . --net yes -- bash` opens a shell with access to just the
current directory.
# Features
* Mount paths read-write or read-only from the host inside the sandbox
* Disable network access
* Isolate from the host processes (separate PID and IPC namespace)
* Reduce the kernel attack surface using seccomp filters
# Security considerations
Without any parameters runjail mounts /etc, /sys and /usr read-only
in the sandbox. Additionally /proc is mounted.
Make sure these directiories don't contain any secret user-readable data
or disable access to them by passing `--hide PATH`.
In the default configuration X11 opens an anonymous socket which makes it
a bit more difficult to prevent sandboxed applications to connect to it.
You can either disable network access from the sandbox or start X11 with
the parameter `-nolisten local`.
# Usage
```
usage: runjail [--flag [--flag ...]] -- [command [command ...]]:
--bind-ro strings Bind mount source file/directory from parent namespace to target read-only (format: "source:target").
--bind-ro-try strings Bind mount source file/directory from parent namespace to target read-only (format: "source:target"). Ignores non-existent source.
--bind-rw strings Bind mount source file/directory from parent namespace to target read-write (format: "source:target").
--bind-rw-try strings Bind mount source file/directory from parent namespace to target read-write (format: "source:target"). Ignores non-existent source.
--config string Fetch options from config file.
--cwd string Set the current working directory. (default ".")
--debug Enable debug mode.
--empty strings Mount empty tmpfs on the specified directory.
--env strings Set the environment variable (format: "name=value").
--hide strings Make file/directory inaccessible.
--hide-try strings Make file/directory inaccessible. Ignore non-existent path.
--ipc Allow IPC (don't start an own IPC namespace).
--net string Enable/disable network access . (default "no")
--profile strings Enable predefined profile: .
--ro strings Mount file/directory from parent namespace read-only.
--ro-try strings Mount file/directory from parent namespace read-only. Ignores non-existent source.
--rw strings Mount file/directory from parent namespace read-write.
--rw-try strings Mount file/directory from parent namespace read-write. Ignores non-existent source.
--seccomp string Enable seccomp syscall filtering: . (default "yes")
```
# Examples
* Open a shell with network access that can access the current directory
`runjail --rw . --net yes -- bash`
* Run firefox in a completely separate home directory and only access to the Downloads folder
`runjail --cwd ~ --bind-rw ~/firefox-test:~ --rw ~/Downloads --profile x11 --net=yes -- firefox -no-remote`
# Config
Instead of passing all settings on the command line you can use --config to read a config file.
A commented example is provided in [config-sample.yml](config-sample.yml)
Wherever paths are accepted `$UID`, `$USER`, `$HOME` and `$XDG_RUNTIME_DIR` with their respective values.
# Requirements
runjail is tested on Linux >= 5.9
It uses unprvileged user namespaces which is disabled by default on some
distributions.
To enable it on Debian (<= 10) the sysctl `kernel.unprivileged_userns_clone` needs
to be set to `1`.
# Building
Golang >= 1.18 and the development files for libseccomp are required.
runjail can be built by running `go build` inside a Git checkout or with
`go get -u github.com/debfx/runjail`
# License
Unless otherwise noted all code of runjail is licensed under the GNU General
Public License version 3 or (at your option) version 2.
The full text of the GPLv3 can be found in the LICENSE file.