Easier to read with cream paper, a tint, more contrast or larger text? Choose your colours and text, once, for every page.

Free lesson

Sandboxing Basics

The whole lesson is free and interactive. Read it here, or press Start lab to run it for real in a live lab, with no account needed.

Virtual machine lab9 min read7 commands

Run code you do not trust

An AI agent writes a script and runs it straight away. A website lets customers upload programs. Nobody can read every line first. So the code is run inside a sandbox, a set of fences the Linux kernel puts round it.

By the end of this lesson

Note

I can put a kernel fence round a program and see what it stops.

Key words

  • Sandbox: fences that limit what a program can reach.
  • Namespace: a private view of one thing, such as the network.
  • cgroup: a group of processes with limits on memory and more.
  • seccomp: a filter on the requests a program makes to the kernel.
  • System call: one request from a program to the kernel.

Starter: what you already know

Note

Answer in your head. 1. Who may read your files when you run a program? 2. What is root? 3. Why might code an AI wrote be risky? You need the first answer in a moment.

Before you start

Note

Press Start the lab on the bar at the top of this lesson. This lab is a whole Ubuntu machine of your own, and the first start installs its tools, so it takes a few minutes. Each Run button types its command into the machine's terminal, one after another in the same session. If one says the machine is still starting, wait a few seconds and press it again. To watch them, or to type your own, press Open terminal on the bar.

Untrusted code runs as you

Your files are in the folder lab. The first command moves into it. agent.py stands in for untrusted code. Asked to read the key in secrets, it prints it: demo-key-4417-not-real. Asked to call out, it says Connection refused: nothing listens on that port, but the network was there.

Command
cd ~/lab

Shown here, not run. Press Start lab to type it into your own lab’s terminal.

Command
python3 agent/agent.py secret

Shown here, not run. Press Start lab to type it into your own lab’s terminal.

Command
python3 agent/agent.py call

Shown here, not run. Press Start lab to type it into your own lab’s terminal.

Check

Tip

Why could the agent read the key? Answer: it runs as you, with every power you have, and you can read your own files.

A namespace takes the network away

unshare --net runs a command in a new network namespace, with no network in it. The same call now says Network is unreachable: there is nothing to connect to at all.

Command
sudo unshare --net python3 agent/agent.py call

Shown here, not run. Press Start lab to type it into your own lab’s terminal.

A cgroup limits memory

sbx limit is the lab's helper. It makes a cgroup with a 64 MB memory limit and runs the agent in it. The agent asks for 200 MB. It prints its first line, then the kernel kills it: sbx says exit status 137 and oom_kill 1.

Command
sudo sbx limit --memory 64M -- python3 agent/agent.py memory 200

Shown here, not run. Press Start lab to type it into your own lab’s terminal.

A common mistake

Warning

Many people think a program over its memory limit gets an error it can deal with. On Linux it is usually killed by the kernel, with no warning, so it never prints its last line.

A seccomp filter refuses calls

sbx seccomp loads an allow-list of system calls. Every call not on the list is refused. The list has no call for opening a network connection, so the agent's call now says Operation not permitted.

Command
sbx seccomp profiles/python.allow -- python3 agent/agent.py call

Shown here, not run. Press Start lab to type it into your own lab’s terminal.

bubblewrap hides a folder

bwrap builds a sandbox from mounts. Here it shows the whole disk read-only and puts an empty folder over secrets. The agent says No such file or directory.

Command
sudo bwrap --ro-bind / / --dev /dev --proc /proc --tmpfs /home/student/lab/secrets python3 agent/agent.py secret

Shown here, not run. Press Start lab to type it into your own lab’s terminal.

Exit check

Tip

Answer without looking back. 1. What does a network namespace take away? 2. What happens to a program over its cgroup memory limit? 3. What does a seccomp allow-list do with a call it does not name? 4. How did bubblewrap hide the key? Answers: every network; the kernel kills it; refuses it; an empty folder on top of it. Now open README.md with cat ~/README.md: you write one script with every fence at once.

For teachers

Tip

This lesson is a small example of a lesson worked in a lab: the steps and the Run buttons are the lesson, and the lab is each student's own copy. This lesson is worked in a VM lab: each student has an Ubuntu machine of their own, and a Run types into its terminal and shows what it printed. Key learning points: 1. Untrusted code runs with every power of the account that starts it. 2. A namespace hides one thing, such as the network. 3. A cgroup limits memory, and the kernel kills a program over it. 4. A seccomp allow-list refuses every call it does not name. Common mistake: thinking a program over its memory limit gets an error. Equipment: the lab and a browser. agent.py is a harmless stand-in and every key is a demo value. Tip: after each fence, ask which of the agent's other tricks it would not stop. The lab itself has a check that marks run-agent.sh with hidden values. Copy it into your own module and change it, or build one from scratch with the Lab menu in the lesson builder.

About this lab and its source: Sandboxing lab: run untrusted code inside namespaces, cgroups, seccomp and gVisor on one private Ubuntu VM

Teaching a class? Set these lessons for your students with marking and a lab for every student.