This article is part of the series Developer-Basics.
TL;DR
- every running program (a process) belongs to a user account
- on Linux, permissions are checked per user
- a sandbox runs programs with fewer rights than its user
- the kernel is the core of the operating system. Every time a process does something, it has to ask the kernel. If the kernel says “no”, there is no way around it
- Landlock is a Linux kernel feature (macOS equivalent: Seatbelt) that can be used by sandboxes
- nolabs.ai nono uses Landlock and is a sandbox you can use for your AI agent. You do not need to care about Landlock at all, everything happens “under the hood” and all you have to do is configure nono
When an AI agent runs a command in your terminal, who is actually running that command? You are. The agent is just another program started from your shell, and it can do everything you can do: read your SSH keys, delete your home directory, push to your repositories. That is exactly why sandboxes are interesting. To understand what a sandbox does, you need three building blocks: users, file permissions and the kernel.
Why would an agent do, what you told them not to do? Apart from the infamous prompt injection, agent configuration and prompts is you kindly asking the agent to follow them. But they do not have to, the rules are not enforced.
This article is the first of a short series with the basics you need to understand nono, a sandbox for AI agents. A second series will go deeper into nono setup and configuration.
Users and Groups
Linux is a multi-user system. Even if you are the only human using your laptop, there are many user accounts on it. Most of them are system users for services, for example http (or www-data on Debian/Ubuntu) for a web server.
When you set up your computer, you most likely have your own user with your name. Internally, the system does not care about names. Every user has a number, the user ID (UID), and every group has a group ID (GID). The names are just a lookup in /etc/passwd and /etc/group.
There are a few core things worth knowing. Firstly, the user with UID 0 is root. Root can bypass most permission checks; you might be used to using it when you invoke commands with sudo. Secondly, a user has one primary group and can be a member of additional groups. Groups are a means to share access.
Check your own user by running id:
$ id
uid=1000(m1rm) gid=1000(m1rm) groups=1000(m1rm),998(wheel)
You see my user, “m1rm”, with UID and GID 1000. I am in my own group, and in the group “wheel”. Being in “wheel” on my OS means my user may use sudo.
Processes
Every running program is a process with a process ID (PID). A process carries the UID and GIDs of the user who started it.
Processes start other processes, and the child inherits the user of its parent. Your terminal runs as you, your shell runs as you, and everything you start from that shell runs as you. Including your AI agent and every command the agent starts. You can see the owner of each process with ps:
$ ps -eo user,pid,comm | head
USER PID COMMAND
root 1 systemd
root 2 kthreadd
...
m1rm 4711 fish
-e selects every process on the system, not only the ones in your terminal. -o user,pid,comm picks the columns: the owner, the PID and the command name. | head cuts the output down to the first ten lines, because the full list is long.
You see systemd with PID 1. It is the first process the kernel starts, and every other process descends from it. kthreadd with PID 2 is the parent of the kernel’s internal threads. Further down you find fish, my shell, running as my user “m1rm”.
Info
sudo does not “give you more rights”. It starts a new process as a different user (root by default), after checking that you are allowed to do that.
File Permission Model
On Linux, (almost) everything is a file: documents, directories, devices, even information about running processes under /proc. So file permissions are the main way access is controlled.
Every file has an owner (a user), a group and three sets of permissions. ls -l shows them:
$ ls -l notes.txt
-rw-r----- 1 m1rm developers 1204 Nov 21 10:00 notes.txt
-l stands for the “long” listing format. From left to right you see the permissions, the number of hard links (1), the owner (m1rm), the group (developers), the size in bytes, the date of the last change and the file name.
Let’s take -rw-r----- apart:
| Position | Value | Meaning |
|---|---|---|
| 1 | - | file type: - regular file, d directory, l symlink |
| 2-4 | rw- | owner (m1rm) may read and write |
| 5-7 | r-- | members of the group (developers) may read |
| 8-10 | --- | others (everyone else) may do nothing |
The three permissions are:
| File | Directory | |
|---|---|---|
r read | read the content | list the entries |
w write | change the content | create, delete, rename entries |
x execute | run it as a program | enter it (cd) and access entries |
The directory column is a common trap: deleting a file is a write operation on its directory, not on the file itself.
When a process wants to access a file, the kernel picks exactly one of the three sets: if the process’s user is the owner, the owner permissions apply. Otherwise, if it is in the file’s group, the group permissions apply. Otherwise, the “others” permissions apply.
You change permissions with chmod and ownership with chown. You will often see permissions written as numbers, where r=4, w=2, x=1 are added up per set:
chmod 640 notes.txt # rw- r-- ---
chmod u+x deploy.sh # add execute for the owner
sudo chown m1rm:developers notes.txt
640 is read digit by digit: 6 (4+2, read and write) for the owner, 4 (read) for the group and 0 (nothing) for others. u+x is the same idea written with letters: u is the owner (user), g the group, o others and a all of them. + adds a permission, - removes it. chown takes the new owner and group separated by a colon. It needs sudo, because only root may hand a file over to another user.
Try it yourself with a file you are not allowed to read. Run ls -l on /etc. You will see root-owned directories and files. Look for a file without r for others, for example /etc/shadow, and try cat as your user (without sudo):
$ cat /etc/shadow
cat: /etc/shadow: Permission denied
cat prints the content of a file. /etc/shadow stores the password hashes of all users, so only root may read it. That “Permission denied” means the kernel refused to open the file.
Tip
This model is called Discretionary Access Control (DAC): the owner of a file decides who can access it. There are extensions such as ACLs for more fine-grained rules.
The Kernel
The kernel is the core of the operating system. It manages hardware, memory, processes and files. Everything else, from your shell to your browser to your AI agent, runs in user space and has no direct access to any of that.
If a program wants to open a file, create a network connection or start another process, it has to ask the kernel via a system call (short: syscall). Opening a file, for example, is the openat syscall. The kernel then checks:
- Who is asking? (the UID/GIDs of the process)
- Is this allowed? (file permissions and other security rules)
- If yes, it does the work and returns the result. If no, it returns an error like
EACCES(“Permission denied”).
You can watch this happen with strace, which prints every syscall a program makes:
$ strace -e trace=openat cat /etc/shadow
...
openat(AT_FDCWD, "/etc/shadow", O_RDONLY) = -1 EACCES (Permission denied)
strace runs the command behind it, here cat /etc/shadow, and logs its syscalls. -e trace=openat limits the output to the openat calls. The ... stands for the files cat opens before, like the libraries it needs to run. In the last line you see the request: open /etc/shadow read-only (O_RDONLY), relative to the current directory (AT_FDCWD). The answer after the = is -1, which means it failed, followed by the reason: EACCES.
This is the key point: the program cannot skip this check. It has no other way to reach the file than to ask the kernel. That is why kernel-level restrictions are so strong. Short of a bug in the kernel itself, there is no way around them.
There is one catch: the kernel checks the process that asks. If that process can talk to another, more privileged program, for example the Docker daemon running as root, that program does the work with its own rights. We will come back to this later in the series.
The file permissions you have seen above are only the first check. The kernel has a framework called Linux Security Modules (LSM) that lets additional security rules hook into these checks. You might have heard of SELinux (Fedora, RHEL) or AppArmor (Ubuntu, openSUSE). Those are LSMs configured by the system administrator. Landlock is an LSM that is made for programs to restrict themselves.
Landlock
Everything so far is based on the user. That is a problem for our AI agent scenario: you want the agent to run as you, so it can work in your project, but you don’t want it to read ~/.ssh or write outside of the project folder. File permissions cannot express “this process may do less than its user”.
Landlock can. It is part of the Linux kernel since version 5.13 (2021) and works like this:
- A process creates a ruleset: “I want to restrict file system access”.
- It adds rules: “allow reading in
/usr, allow reading and writing in~/projects/my-app”. - It calls
landlock_restrict_selfand the rules are enforced from now on.
Landlock works as an allow-list: everything that is not explicitly allowed is denied. That is the safer default. If you forget a rule, something breaks, but no hole opens up.
Some properties make Landlock a good fit for sandboxes:
- No root needed. Any program can sandbox itself, no administrator setup required.
- Restrictions are inherited. All child processes are restricted as well, so a sandboxed agent cannot escape by starting a new shell.
- One way only. Restrictions can be added later, but never removed. A sandboxed process cannot “unsandbox” itself.
- It stacks on top. Landlock can only take rights away. If the file permissions say “no”, Landlock cannot turn that into a “yes”. It applies even to processes running as root.
The first version only covered file system access. Newer kernels added more, for example restricting TCP connections (6.7). You can check if Landlock is active on your system:
$ cat /sys/kernel/security/lsm
capability,landlock,lockdown,yama,bpf
This file lists all security modules that are active on your system. If landlock is in the list, you are good to go. If not, your kernel was built or booted without it.
In practice, you will rarely call Landlock yourself. A sandbox tool or your agent CLI does it for you, for example nono, which this series builds up to. It sets up the rules and then starts the actual command inside the restricted process. If you want to play with it, the kernel ships a small sandboxer example, and landlock.io lists libraries and tools.
Info
Landlock is not the only building block. Sandboxes on Linux often combine it with seccomp (limits which syscalls are allowed at all) and namespaces (give a process its own view of the file system, network or process list, the basis of containers).
Big Picture Summarized
Putting it all together, this is what happens when your AI agent runs cat ~/.ssh/id_ed25519 inside a sandbox:
- Users and groups define who a process is.
- File permissions define what that user may do with a file.
- The kernel checks every single access, and programs cannot bypass it.
- A sandbox uses kernel features like Landlock to give a process fewer rights than its user, and those restrictions are inherited by everything it starts.
Without a sandbox, step 3 does not exist and the agent can read your private key, because you can.
This is where nono comes in: it sets up step 3 for your agent, so all you have to decide is what the agent may access. The next articles in this series cover the remaining basics you need for that.
Further Reading
- nono on GitHub and the nono documentation: the sandbox this series builds up to
- The Linux Command Line by William Shotts: a free book (PDF) covering the shell, permissions and processes in more depth
- Landlock kernel documentation: the full API including all ABI versions and code examples
- Access Control Lists, acl(5): fine-grained permissions beyond owner/group/others
- Capabilities, capabilities(7): how root’s powers are split into smaller pieces
- seccomp(2): filtering which syscalls a process may use
- Namespaces, namespaces(7): the kernel feature behind containers
- bubblewrap: a small, unprivileged sandboxing tool built on namespaces, used by Flatpak
- Linux Security Modules: overview of SELinux, AppArmor, Landlock and friends
Sources
- credentials(7), Linux man-pages: process IDs, user and group IDs
- path_resolution(7), Linux man-pages: how the kernel checks file permissions
- chmod(1), Linux man-pages
- syscalls(2), Linux man-pages
- landlock(7), Linux man-pages
- Landlock: unprivileged access control, Linux kernel documentation
- landlock.io, Landlock project website
- Linux Security Module Usage, Linux kernel documentation
- Users and groups, ArchWiki
- File permissions and attributes, ArchWiki
- strace, project website
