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
| Word | What it means | Example |
|---|---|---|
| WASI | the WebAssembly System Interface, standard imports for files and more | |
| Capability | a handle that lets a program use one thing | |
| Preopened folder | a folder the host opens and hands over | --dir data |
| Environment variable | a named setting passed to a program | CITY=Leeds |
| File descriptor | a number that stands for an open file or folder | |
| Error code | a 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
docker exec wasm wasmtime run cat.wat notes.txtShown here, not run. Press Start lab to type it into your own lab’s terminal.
Grant the data folder and ask again
docker exec wasm wasmtime run --dir data cat.wat notes.txtShown 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
docker exec wasm wasmtime run --dir data cat.wat ../private/key.txtShown here, not run. Press Start lab to type it into your own lab’s terminal.
Worked example: what each refusal meant
| Command | Printed | Why |
|---|---|---|
| cat.wat notes.txt | WASI error 8 | No folder granted, so no handle |
| --dir data cat.wat notes.txt | the shopping list | The file is inside the folder |
| --dir data cat.wat ../private/key.txt | WASI error 63 | The path leaves the folder |
| --dir data cat.wat missing.txt | WASI error 44 | Inside, 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?
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
docker exec wasm wasmtime run env.watShown here, not run. Press Start lab to type it into your own lab’s terminal.
Grant one variable and list again
docker exec wasm wasmtime run --env CITY=Leeds env.watShown here, not run. Press Start lab to type it into your own lab’s terminal.