capsh

capsh [options] [--] [command [args...]]

--print
    Prints the current capability sets (effective, permitted, inheritable, bounding, ambient), security bits, and UID/GID information.

--decode=VALUE
    Decodes a hexadecimal capability bitmask VALUE into a human-readable list of capabilities.

--drop=CAPS
    Drops specified capabilities from the current process's effective, permitted, and inheritable sets. CAPS is a comma-separated list of capabilities (e.g., cap_net_raw,cap_sys_ptrace) or 'all'.

--add=CAPS
    Adds specified capabilities to the current process's effective and permitted sets. Requires appropriate privileges to add capabilities not already present in the bounding set or the parent's inheritable set. CAPS format is the same as --drop.

--caps=CAPS
    Explicitly sets the effective, permitted, and inheritable capability sets for the process. CAPS is a string like 'cap_net_raw=eip cap_chown=p'.

--user=NAME
    Sets the effective and real user ID to that of NAME. Implies dropping privileges unless --keep=1 is used.

--uid=ID
    Sets the effective and real user ID to ID. Similar to --user, implies privilege dropping.

--gid=ID
    Sets the effective and real group ID to ID.

--groups=GIDS
    Sets the supplementary group IDs to the comma-separated list of GIDS.

--chroot=DIR
    Performs a chroot(2) operation into DIR before executing a command or shell.

--chown=UID:GID
    Changes the ownership of the --chroot directory (if specified) to UID:GID before the chroot operation. Requires cap_chown.

--target=PID
    Targets a running process specified by its Process ID (PID) to retrieve or manipulate its capabilities. Requires CAP_SYS_PTRACE.

--bounding=CAPS
    Sets the bounding capability set. Capabilities not in the bounding set cannot be gained or passed by `execve`.

--ambient=CAPS
    Sets the ambient capability set. Capabilities in the ambient set are preserved across `execve` of non-privileged executables.

--inhb=CAPS
    Sets the inheritable capability set for the process. These are capabilities that can be inherited by child processes (if also present in the file's permitted set).

--secbits=VALUE
    Sets the security bits, which control various capability-related behaviors (e.g., SECBIT_NO_SETUID_FIXUP, SECBIT_NO_CAP_AMBIENT_RAISE).

--keep=1
    When used with --uid or --user, this flag prevents `execve` from clearing permitted capabilities when switching from root (UID 0) to a non-root user. This is crucial for retaining capabilities when dropping privileges.

--command=FILE
    Executes the specified FILE as a command. This is an alternative to placing the command after --.

--
    Separates capsh specific options from the command and its arguments that should be executed. Any arguments following -- are treated as the command and its arguments.

The capsh command is a powerful utility from the libcap package, designed to inspect, modify, and test the Linux process capabilities for the current shell or a specified command. It allows administrators and developers to simulate privilege changes, drop or add specific capabilities, change user/group IDs, and manage security-related attributes like bounding and ambient capability sets. This tool is invaluable for understanding how capabilities affect program execution and for designing applications that run with the minimal necessary privileges, enhancing system security by adhering to the principle of least privilege.

Using capsh effectively requires a deep understanding of Linux capabilities (Effective, Permitted, Inheritable, Bounding, Ambient sets) and how they interact with privilege changes and `execve` calls. Incorrect use can lead to unexpected privilege escalation or privilege reduction. Many operations, especially adding or retaining capabilities, require root privileges or existing specific capabilities. Changes made by capsh are temporary and only affect the process it launches. The --target option requires CAP_SYS_PTRACE and can only inspect capabilities, not modify them directly on an external process.

Linux capabilities are divided into several sets for each process: Effective (E) - the capabilities currently active and used by the process; Permitted (P) - the maximum set of capabilities a process can ever possess; Inheritable (I) - capabilities that are preserved across an execve(2) system call; Bounding (B) - a master set that limits the capabilities a process can ever obtain; and Ambient (A) - capabilities that are preserved across `execve` of non-privileged executables, bridging the gap between file capabilities and inherited capabilities.

When capsh changes the UID/GID to a non-root user, the kernel by default drops all permitted capabilities, adhering to the principle of least privilege. The --keep=1 option is essential if you intend for the process to retain certain capabilities even after switching from UID 0 to a non-zero UID. This allows for fine-grained control over retained privileges during privilege dropping.

The capsh utility is an integral part of the libcap project, which provides the user-space libraries and tools for Linux capabilities. It emerged as a necessary tool to interact with and test the Linux capability system, which replaced the traditional all-or-nothing root privilege model. Its development has mirrored the evolution of Linux capabilities, including the introduction of ambient capabilities and further refinements, making it a critical diagnostic and testing tool for secure application deployment.

capabilities(7), setcap(8), getcap(8), prctl(2), execve(2)