CAPSICUM(4)

📦 version 12.2, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

💖 CAPSICUM(4) 💖

okay bestie, gather round, because we're talking about Capsicum — the lightweight OS capability and sandbox framework, and she is that girl. this is a kernel interfaces manual page, so yes we're in section 4, and yes it's giving iconic security architecture. 🎀

✨ SYNOPSIS ✨

options CAPABILITY_MODE
options CAPABILITIES

that's it. that's the whole vibe. two kernel options and you're in business. 💅

🌸 DESCRIPTION 🌸

so, Capsicum is a lightweight OS capability and sandbox framework implementing a hybrid capability system model. no cap. and what is it for? bestie, it's for:

  • application and library compartmentalisation
  • the decomposition of larger bodies of software into isolated (sandboxed) components

...in order to implement security policies and limit the impact of software vulnerabilities. literally the "don't let one bug take down the whole app" agenda and we are obsessed. 🦋

Capsicum provides two core kernel primitives, and they are the main characters:

  • capability mode — a process mode, entered by invoking cap_enter(2), in which access to global OS namespaces (such as the file system and PID namespaces) is restricted; only explicitly delegated rights, referenced by memory mappings or file descriptors, may be used. and here's the spicy part: once set, the flag is inherited by future children processes, and may not be cleared. so like, choose your fate carefully, because it's permanent. periodt. 😭
  • capabilities — limit operations that can be called on file descriptors. for example, a file descriptor returned by open(2) may be refined using cap_rights_limit(2) so that only read(2) and write(2) can be called, but not fchmod(2). the complete list of the capability rights can be found in the rights(4) manual page. it's giving "you can come in but you can't touch anything." ✨

🫶 the "we need alternatives" section 🫶

in some cases, Capsicum requires use of alternatives to traditional POSIX APIs in order to name objects using capabilities rather than global namespaces:

  • process descriptors — file descriptors representing processes, allowing parent processes to manage child processes without requiring access to the PID namespace; described in greater detail in procdesc(4).
  • anonymous shared memory — an extension to the POSIX shared memory API to support anonymous swap objects associated with file descriptors; described in greater detail in shm_open(2).

💜 the "we're limiting your options, babe" section 💜

in some cases, Capsicum limits the valid values of some parameters to traditional APIs in order to restrict access to global namespaces:

  • process IDs — processes can only act upon their own process ID with syscalls such as cpuset_setaffinity(2).

like, mind your own business, but make it a kernel feature. 🙈

🔥 SEE ALSO 🔥

go read these next, i'm literally begging you:

⭐ HISTORY ⭐

Capsicum first appeared in FreeBSD 9.0, and was developed at the University of Cambridge. ✨ academic baddies, we love to see it.

👑 AUTHORS 👑

Capsicum was developed by:

  • Robert Watson <rwatson@FreeBSD.org>
  • Jonathan Anderson <jonathan@FreeBSD.org>

...at the University of Cambridge, and:

  • Ben Laurie <benl@FreeBSD.org>
  • Kris Kennaway <kris@FreeBSD.org>

...at Google, Inc., and:

  • Pawel Jakub Dawidek <pawel@dawidek.net>

a whole squad of legends fr fr. 🫶

💀 friendly reminder: capability mode is irreversible. once you cap_enter(2), you can't take it back. no take-backs, no undo, no "wait actually". it's a one-way door and it is locked.

okay that's the whole page, bestie!! this one came from the Debian distro flavour of things, dated May 18, 2017, and you just read the CAPSICUM(4) manual page — sandbox yourself responsibly, mwah 💋💖🧚

📦 where this page comes from