1.\" 2.\" Copyright (c) 2011, 2013 Robert N. M. Watson 3.\" Copyright (c) 2011 Jonathan Anderson 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 16.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 17.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 18.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 19.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 20.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 21.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 22.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 23.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 24.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 25.\" SUCH DAMAGE. 26.\" 27.Dd June 17, 2025 28.Dt CAPSICUM 4 29.Os 30.Sh NAME 31.Nm Capsicum 32.Nd lightweight OS capability and sandbox framework 33.Sh SYNOPSIS 34.Cd "options CAPABILITY_MODE" 35.Cd "options CAPABILITIES" 36.Sh DESCRIPTION 37.Nm 38is a lightweight OS capability and sandbox framework implementing a hybrid 39capability system model. 40.Nm 41is designed to blend capabilities with UNIX. 42This approach achieves many of the benefits of least-privilege operation, while 43preserving existing UNIX APIs and performance, and presents application authors 44with an adoption path for capability-oriented design. 45.Pp 46Capabilities are unforgeable tokens of authority that can be delegated and must 47be presented to perform an action. 48.Nm 49makes file descriptors into capabilities. 50.Pp 51.Nm 52can be used for application and library compartmentalisation, the 53decomposition of larger bodies of software into isolated (sandboxed) 54components in order to implement security policies and limit the impact of 55software vulnerabilities. 56.Pp 57.Nm 58provides two core kernel primitives: 59.Bl -tag -width indent 60.It capability mode 61A process mode, entered by invoking 62.Xr cap_enter 2 , 63in which access to global OS namespaces (such as the file system and PID 64namespaces) is restricted; only explicitly delegated rights, referenced by 65memory mappings or file descriptors, may be used. 66Once set, the flag is inherited by future children processes, and may not be 67cleared. 68.Pp 69Access to system calls in capability mode is restricted: some system calls 70requiring global namespace access are unavailable, while others are 71constrained. 72For instance, 73.Xr sysctl 2 74can be used to query process-local information such as address space layout, 75but also to monitor a system’s network connections. 76.Xr sysctl 2 77is constrained by explicitly marking \(~~60 of over 15000 parameters as permitted 78in capability mode; all others are denied. 79.Pp 80The system calls which require constraints are 81.Xr sysctl 2 , 82.Xr shm_open 2 83.Pq which is permitted to create anonymous memory objects but not named ones 84and the 85.Xr openat 2 86family of system calls. 87The 88.Xr openat 2 89calls already accept a file descriptor argument as the directory to perform the 90.Xr open 2 , 91.Xr rename 2 , 92etc. relative to; in capability mode the 93.Xr openat 2 94family of system calls are constrained so that they can only operate on 95objects “under” the provided file descriptor. 96.It capabilities 97Limit operations that can be called on file descriptors. 98For example, a file descriptor returned by 99.Xr open 2 100may be refined using 101.Xr cap_rights_limit 2 102so that only 103.Xr read 2 104and 105.Xr write 2 106can be called, but not 107.Xr fchmod 2 . 108The complete list of the capability rights can be found in the 109.Xr rights 4 110manual page. 111.El 112.Pp 113In some cases, 114.Nm 115requires use of alternatives to traditional POSIX APIs in order to name 116objects using capabilities rather than global namespaces: 117.Bl -tag -width indent 118.It process descriptors 119File descriptors representing processes, allowing parent processes to manage 120child processes without requiring access to the PID namespace; described in 121greater detail in 122.Xr procdesc 4 . 123.It anonymous shared memory 124An extension to the POSIX shared memory API to support anonymous swap objects 125associated with file descriptors; described in greater detail in 126.Xr shm_open 2 . 127.El 128.Pp 129In some cases, 130.Nm 131limits the valid values of some parameters to traditional APIs in order to 132restrict access to global namespaces: 133.Bl -tag -width indent 134.It process IDs 135Processes can only act upon their own process ID with syscalls such as 136.Xr cpuset_setaffinity 2 . 137.El 138.Pp 139.Fx 140provides some additional functionality to support application sandboxing that 141is not part of 142.Nm 143itself: 144.Bl -tag -width indent 145.It Xr capsicum_helpers 3 146A set of a inline functions which simplify modifying programs to use 147.Nm . 148.It Xr libcasper 3 149A library that provides services for sandboxed applications, such as operating 150on files specified on a command line or establishing network connections. 151.El 152.Sh SEE ALSO 153.Xr cap_enter 2 , 154.Xr cap_fcntls_limit 2 , 155.Xr cap_getmode 2 , 156.Xr cap_ioctls_limit 2 , 157.Xr cap_rights_limit 2 , 158.Xr fchmod 2 , 159.Xr open 2 , 160.Xr pdfork 2 , 161.Xr pdgetpid 2 , 162.Xr pdkill 2 , 163.Xr pdwait4 2 , 164.Xr read 2 , 165.Xr shm_open 2 , 166.Xr write 2 , 167.Xr cap_rights_get 3 , 168.Xr capsicum_helpers 3 , 169.Xr libcasper 3 , 170.Xr procdesc 4 171.Sh HISTORY 172.Nm 173first appeared in 174.Fx 9.0 , 175and was developed at the University of Cambridge. 176.Sh AUTHORS 177.Nm 178was developed by 179.An -nosplit 180.An Robert Watson Aq Mt rwatson@FreeBSD.org 181and 182.An Jonathan Anderson Aq Mt jonathan@FreeBSD.org 183at the University of Cambridge, and 184.An Ben Laurie Aq Mt benl@FreeBSD.org 185and 186.An Kris Kennaway Aq Mt kris@FreeBSD.org 187at Google, Inc., and 188.An Pawel Jakub Dawidek Aq Mt pawel@dawidek.net . 189Portions of this manual page are drawn from 190.Rs 191.%A Robert N. M. Watson 192.%A Jonathan Anderson 193.%A Ben Laurie 194.%A Kris Kennaway 195.%T Capsicum: practical capabilities for UNIX 196.%J USENIX Security Symposium 197.%D August 2010 198.%O DOI: 10.5555/1929820.1929824 199.Re 200