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

Free lesson

WebAssembly as a plugin sandbox

After this lesson: I can choose limits that stop a WebAssembly plugin from harming its host.

65 min lesson4 commandsWebAssembly lab: Wasmtime, WASI capabilities, WIT components and plugin limits

Running a stranger's code inside your program

A plugin sandbox lets an application run code written by somebody else without trusting it. Editors, web proxies, databases and games use WebAssembly for this. A plugin can only call what the host imports into it, and the host can stop it.

Today you stop a plugin that never ends and one that wants too much memory.

By the end of this lesson

Note

I can choose limits that stop a WebAssembly plugin from harming its host.

Key words

WordWhat it meansExample
Plugincode that adds a feature to a host program
Hostthe program that loads and runs the plugin
Trapan error that stops the WebAssembly code at once
Fuela budget of work that runs down as code runs-W fuel=100000
Timeouta limit on how long code may run-W timeout=2s
Pageone 64 KiB block of WebAssembly memory

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

How do you stop an endless plugin?

spin.wat is a plugin with a loop and no way out. Run as it is, it would hold the processor for ever.

Wasmtime has two brakes. A timeout counts real time: the runtime ticks a counter, and the code checks it at loops and calls. Fuel counts work: every instruction spends some, and the plugin traps when the tank is empty.

Stop it after two seconds

Command
docker exec wasm wasmtime run -W timeout=2s spin.wat

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

Stop it when its fuel runs out

Command
docker exec wasm wasmtime run -W fuel=100000 spin.wat

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

Worked example: two ways to stop a plugin

BrakeWhat it countsThe trap printedGood for
TimeoutReal timewasm trap: interruptA request that must answer quickly
FuelWork donewasm trap: all fuel consumed by WebAssemblyThe same limit on every machine

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

A plugin's memory has a ceiling

Memory grows a page of 64 KiB at a time. grow.wat asks for one more page until the answer is no, then prints how many it holds.

The module itself says at most 100 pages. The host can set a lower ceiling with -W max-memory-size. Asked for more, memory.grow answers -1 and the plugin carries on, so a careful plugin can cope.

Let the plugin grow to its own limit

Command
docker exec wasm wasmtime run grow.wat

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

Give the plugin one mebibyte

Command
docker exec wasm wasmtime run -W max-memory-size=1048576 grow.wat

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

Try it: turn a limit into pages

Code: python
PAGE = 64 * 1024   # one WebAssembly page is 64 KiB

for limit in [1048576, 4 * 1048576, 64 * 1048576]:
    print(limit, "bytes allow", limit // PAGE, "pages")
# Which limit, in bytes, allows exactly 100 pages?

A common mistake

Warning

Many people think the sandbox makes a plugin safe whatever the host gives it. A plugin can misuse every function the host imports into it. Grant it a folder or the network, and it can use them. The sandbox only removes what you did not give.

What the sandbox does not do

Wasm keeps a plugin inside its own memory, but some risks stay. A bug in a host function you wrote is still a bug. The runtime itself can have bugs, so keep it up to date. Timing tricks can leak secrets between plugins in one process.

Crossing the boundary also costs time, because values are copied. So pass a batch of work in one call, not one value per call.

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.