cage

Run an application

$ cage [application]

$ cage -- [application] [arguments]

$ cage -h

cage [OPTIONS] [--] COMMAND [ARG...]

-u USER, --user=USER
    Map the current user to USER inside the cage. The user ID is remapped within the user namespace.

-g GROUP, --group=GROUP
    Map the current user's primary group to GROUP inside the cage. The group ID is remapped within the user namespace.

-b DIR, --bind=DIR
    Bind mount an existing directory DIR from the host into the cage at the same path. Can be specified multiple times.

-m TYPE:DEVICE:DIR:OPTIONS, --mount=TYPE:DEVICE:DIR:OPTIONS
    Mount a filesystem or device into the cage. For example, tmpfs:none:/tmp:size=10m.

-t SIZE, --tmpfs=SIZE
    Mount a tmpfs at /tmp inside the cage, with an optional SIZE limit (e.g., 10M).

-e VAR=VALUE, --env=VAR=VALUE
    Set an environment variable inside the cage for the executed command.

--proc
    Mount a private /proc filesystem instance inside the cage, isolating process information.

--devfs
    Mount a private /dev filesystem instance inside the cage, limiting device access.

--sysfs
    Mount a private /sys filesystem instance inside the cage, isolating system information.

--no-pty
    Do not allocate a pseudo-terminal (PTY) for the caged command, useful for non-interactive processes.

--noroot
    Prevent the user from gaining root privileges inside the cage, even if UID 0 is mapped.

--uid-map=HOST_UID:CAGE_UID:COUNT
    Map a range of host UIDs to a range of UIDs inside the cage, enhancing user isolation.

--gid-map=HOST_GID:CAGE_GID:COUNT
    Map a range of host GIDs to a range of GIDs inside the cage, enhancing group isolation.

--cap-add=CAPABILITY
    Add a specific Linux capability to the caged process. Can be specified multiple times.

--cap-drop=CAPABILITY
    Drop a specific Linux capability from the caged process, reducing potential attack surface.

The cage command provides a lightweight sandboxing mechanism for running untrusted applications or processes in a restricted environment. It creates an isolated execution context, often referred to as a "cage," by leveraging Linux kernel features such as namespaces (mount, PID, user, network, UTS, IPC) and cgroups.

Unlike a simple chroot, cage offers more comprehensive isolation, including the ability to remap user and group IDs, prevent access to host filesystems and devices, set resource limits, and provide private instances of essential directories like /proc and /dev. This enhances security by limiting the potential damage an application can inflict if compromised, making it a valuable tool for running potentially malicious or buggy code safely.

Configuring cage for optimal security can be complex and requires a good understanding of Linux namespaces, capabilities, and filesystem permissions. Misconfigurations can inadvertently lead to security vulnerabilities or allow processes to break out of the cage.

While cage provides strong isolation, it is not a full virtualization solution like a virtual machine or a comprehensive container platform like Docker, which offer additional layers of isolation and orchestration. It is primarily designed for single-process sandboxing rather than hosting full operating system environments.

cage is particularly useful for:
- Running untrusted scripts or binaries from unknown sources.
- Isolating build environments for compiling software.
- Providing a secure, minimal environment for specific network services.
- Testing applications in a controlled, isolated filesystem.

To use cage effectively, the underlying Linux kernel must support namespaces (mount, PID, user, network, IPC, UTS) and cgroups. While cage can often be run by non-root users (if configured with user namespace support), setting up complex cage environments, especially involving bind mounts or device mounts, often requires root privileges.

The cage command is part of the usermode package, which emerged primarily within the Red Hat/Fedora ecosystem around the early 2000s. Its development was driven by the need for a lightweight, user-friendly sandboxing tool that could leverage evolving Linux kernel features like namespaces to isolate processes more effectively than a simple chroot.

It provides a more robust security boundary for running untrusted applications or creating isolated build environments without the overhead of full virtual machines. While not as widely known as modern container runtimes like Docker, cage remains a stable and effective tool for its specific niche in lightweight process isolation.

chroot(1), unshare(1), nsenter(1), systemd-nspawn(1), firejail(1), namespaces(7), cgroups(7)