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

Free lesson

Wasmtime and the capability model

After this lesson: I can decide what a Wasmtime command lets a program reach.

60 min lesson5 commandsWebAssembly lab: Wasmtime, WASI capabilities, WIT components and plugin limits

A program that cannot read your files

Wasmtime runs a WebAssembly program with no files, no environment variables and no network, unless you grant each one on the command line. This is the capability model, and it means a program you did not write cannot read what you did not give it.

Today you grant a folder and a variable, and watch everything else being refused.

By the end of this lesson

Note

I can decide what a Wasmtime command lets a program reach.

Key words

WordWhat it meansExample
WASIthe WebAssembly System Interface, standard imports for files and more
Capabilitya handle that lets a program use one thing
Preopened foldera folder the host opens and hands over--dir data
Environment variablea named setting passed to a programCITY=Leeds
File descriptora number that stands for an open file or folder
Error codea number WASI returns when it refuses

The cells students fill in are left blank in this preview.

Why ask for every file?

An ordinary program can open any file its user may read. That is ambient authority: the power is in the air around it, and a bad library gets all of it.

A WASI program starts with nothing. To read files, the host opens a folder and hands the program a file descriptor for it. The program can then open paths inside that folder, and no others.

Ask for a file with nothing granted

Command
docker exec wasm wasmtime run cat.wat notes.txt

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

Grant the data folder and ask again

Command
docker exec wasm wasmtime run --dir data cat.wat notes.txt

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

A granted folder is a fence

Error 8 means there was no folder handle at all. With --dir data, the program got one, so notes.txt opened.

Now ask for ../private/key.txt. The private folder sits right beside data, and the user running wasmtime could read it. WASI still refuses, because the path climbs out of the folder that was granted.

Try to climb out of the folder

Command
docker exec wasm wasmtime run --dir data cat.wat ../private/key.txt

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

Worked example: what each refusal meant

CommandPrintedWhy
cat.wat notes.txtWASI error 8No folder granted, so no handle
--dir data cat.wat notes.txtthe shopping listThe file is inside the folder
--dir data cat.wat ../private/key.txtWASI error 63The path leaves the folder
--dir data cat.wat missing.txtWASI error 44Inside, but no such file

The cells students fill in are left blank in this preview.

A common mistake

Warning

Many people think a WASI program can read whatever the user running wasmtime can read. It reaches only the folders given with --dir, and nothing above them. Even run by root, it cannot open a file outside its folders.

Try it: does a path stay inside?

Code: python
def stays_inside(path):
    # Walk the path a part at a time. ".." may never climb above the folder.
    if path.startswith("/"):
        return False
    depth = 0
    for part in path.split("/"):
        if part == "..":
            depth = depth - 1
            if depth < 0:
                return False
        elif part != "" and part != ".":
            depth = depth + 1
    return True

for path in ["notes.txt", "week1/../notes.txt", "../private/key.txt", "/etc/passwd"]:
    print(path, "stays inside:", stays_inside(path))
# Add "week1/../../key.txt". Does it stay inside?

Environment variables are not passed on

A program started by a shell normally sees every variable the shell has, passwords included. Wasmtime passes none.

Use --env NAME=value to set one, or --env NAME to pass one the host already has. The option -S inherit-env passes them all, so use it only when you trust the program. The network is the same: nothing is reachable until an -S option grants it.

List the variables with none granted

Command
docker exec wasm wasmtime run env.wat

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

Grant one variable and list again

Command
docker exec wasm wasmtime run --env CITY=Leeds env.wat

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

About this lab and its source: WebAssembly lab: Wasmtime, WASI capabilities, WIT components and plugin limits

Teaching a class? Set this module for your students with a teacher guide, marked assignments and a lab for every student.