A program that can only touch what you give it
WebAssembly is a small binary format for programs that runs on any machine with a runtime. Outside the browser it runs plugins and tools in a sandbox: the program can reach no file, setting or network unless the runtime is told to hand it over. This lab runs Wasmtime, the runtime from the Bytecode Alliance.
By the end of this lesson
Note
I can run a WebAssembly program with Wasmtime and grant it only what it needs.
Key words
- WebAssembly: a portable binary format for programs.
- Runtime: the program that runs WebAssembly, here Wasmtime.
- WASI: the standard way a WebAssembly program asks for files and settings.
- Capability: one thing a program has been given, such as a folder.
- Component: a WebAssembly program with typed imports and exports.
- Fuel: a budget of work that stops a program when it runs out.
Starter: what you already know
Note
Answer in your head. 1. Can a program built for a laptop run unchanged on a phone? 2. What is a folder permission for? 3. Why would you not run a program from a stranger on your own computer? Answers: usually not, it was built for one kind of processor; to say who may read or change files; it could read or delete your files.
Before you start
Note
Press Start the lab on the bar at the top of this lesson and wait until it says it is running. There are two services. wasm runs Wasmtime and has no shell, so each Run is docker exec wasm wasmtime .... tools has Python and a shell, and both see the same folder. Each Run button below types its command into your lab's terminal, one after another in the same session. To watch them, or to type your own, press Open terminal on the bar.
Run a first program
hello.wat is a WebAssembly program written in the text format, which Wasmtime reads directly. It asks WASI for one thing, a way to write text, and prints Hello from WebAssembly.
docker exec wasm wasmtime run hello.watShown here, not run. Press Start lab to type it into your own lab’s terminal.
Ask for a file with nothing granted
cat.wat prints a file. Here no folder was granted, so it has nowhere to look and prints cannot open notes.txt: WASI error 8. The file is right there in the data folder, but the program was not given that folder.
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 one folder
The option --dir data hands the program the data folder and nothing else. Now it prints the shopping list: Shopping for Saturday, bread, milk, eggs. A path that climbs out of the folder, such as ../private/key.txt, would still be refused.
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.
Grant one setting
env.wat lists its environment variables. Wasmtime passes none unless told to, so a password in the host's settings stays private. With --env CITY=Leeds it prints CITY=Leeds and nothing more.
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.
Check
Tip
Why did cat.wat fail the first time even though notes.txt exists? Answer: no folder was granted, so the program had no way to reach any file.
Call a component by name
calc.wat is a component: a program with typed functions, described in calc.wit. Wasmtime calls its add with the numbers 2 and 3 and prints 5.
docker exec wasm wasmtime run --invoke 'add(2, 3)' calc.watShown here, not run. Press Start lab to type it into your own lab’s terminal.
Run two components joined into one
doubler.wat needs an add function it does not have. app.wat joins it to calc.wat, so doubler uses calc's add. Asked to double 21, it prints 42. Run on its own, doubler would be refused because nothing gives it add.
docker exec wasm wasmtime run --invoke 'double(21)' app.watShown here, not run. Press Start lab to type it into your own lab’s terminal.
Stop a program that never ends
spin.wat loops for ever. Given a budget of 100000 units of fuel, it runs until the budget is spent, and Wasmtime stops it with wasm trap: all fuel consumed by WebAssembly. Wasmtime itself carries on.
docker exec wasm wasmtime run -W fuel=100000 spin.watShown here, not run. Press Start lab to type it into your own lab’s terminal.
A common mistake
Warning
Many people think a WebAssembly program can read anything the person running it can read. It can only use what Wasmtime hands it, such as one folder or one setting. Give it the least it needs, because whatever you do grant, it can use.
Exit check
Tip
Answer without looking back. 1. Which option hands a program a folder? 2. Which environment variables does a program see by default? 3. Why was doubler.wat refused on its own? 4. What stops a program that never ends? Answers: --dir; none; nothing gave it add; a fuel budget or a time limit.
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. The lab is two services, Wasmtime with no shell and a Python service that writes the files, and nothing here marks itself: the student hands in a short write-up of one experiment with the commands and what Wasmtime printed. Key learning points: 1. A WebAssembly program reaches only what the runtime grants. 2. A component has typed imports and exports, and two can be joined. 3. Fuel or a time limit stops a runaway program. Common mistake: thinking the program can read whatever its user can. Equipment: the lab and a browser. Tip: show the data and private folders side by side before the third Run. Copy it into your own module and change it, or build one from scratch with the Lab menu in the lesson builder.