Getting started with Kettlecorn

Copy Markdown View Source
Mix.install([{:kettlecorn, "~> 0.1.0"}])

About this notebook

Kettlecorn runs untrusted Elixir and Erlang in a sandbox. Each VM runs OTP and Elixir in its own launcher process, using a BEAM emulator compiled to WebAssembly. This notebook covers evaluation, persistent state, errors, isolation, and limits. The host is this Livebook runtime; the guest is the OTP system running inside Wasmtime.

Requires Elixir 1.20 or later on x86_64 or ARM64 Linux or Apple silicon macOS. Run the cells in order. Kettlecorn is experimental; bugs in it or its dependencies may compromise isolation. Read sandbox and resource limits before using it with untrusted workloads.

Install the runtime

The Hex package doesn't contain the runtime: the emulators and the guest's OTP and Elixir. Kettlecorn.Install.runtime/1 downloads the archive for this library version from its GitHub release, checks its SHA-256, and unpacks it into your user cache directory. Kettlecorn finds it there automatically. The archive includes the native launcher for your platform with an embedded Wasmtime engine.

{:ok, runtime} = Kettlecorn.Install.runtime()

mix kettlecorn.install does the same from a Mix project.

Run one evaluation

Kettlecorn.run/2 starts a fresh VM, evaluates code, and stops it. Use this when runs must not share state:

{:ok, %{"value" => 120}} =
  Kettlecorn.run("Enum.reduce(1..5, &*/2)",
    max_fuel: 50_000_000_000,
    max_lifetime: 10_000
  )

Reuse a VM

max_fuel limits total execution in Wasmtime fuel units (roughly WebAssembly instructions), and max_lifetime limits elapsed time in milliseconds. Both include startup and apply across all evaluations in a VM.

Kettlecorn.start_link/1 starts the launcher, boots OTP, and returns once the guest is ready. The first start compiles the emulator. Later starts use the launcher's cache, but still copy the runtime and boot OTP; see the performance guide. The following VM has a ten-minute lifetime for reading and running these cells. Restart from this cell if it expires.

{:ok, vm} =
  Kettlecorn.start_link(
    max_memory: 256 * 1024 * 1024,
    max_fuel: 1_000_000_000_000,
    max_lifetime: 600_000
  )

Evaluate code

Kettlecorn.eval/3 returns the formatted result and captured standard output. For bounded plain data, it also returns the value itself:

{:ok,
 %{
   "value" => [{1, 1}, {2, 4}, {3, 9}],
   "inspected" => "[{1, 1}, {2, 4}, {3, 9}]",
   "output" => "hi\n"
 }} = Kettlecorn.eval(vm, ~S|IO.puts("hi"); Enum.map(1..3, fn n -> {n, n * n} end)|)

"value" is structured data; "inspected" is its formatted text. Writes to stderr bypass "output" and go to the VM's console output. Retrieve console stdout and stderr together with Kettlecorn.take_output/1, or configure an owner: pid to receive events labeled :stdout and :stderr.

The VM runs OTP. Processes, ETS, regular expressions and protocols all work, and state persists between evaluations:

{:ok, _} =
  Kettlecorn.eval(vm, """
  defmodule Greeter do
    def hello(name), do: "Hello, \#{name}!"
  end
  """)

{:ok, %{"value" => "Hello, Ada!"}} = Kettlecorn.eval(vm, ~S|Greeter.hello("Ada")|)

Variables bound by evaluated code are local to that evaluation. The module above remains loaded, but this variable does not:

{:ok, %{"value" => 42}} = Kettlecorn.eval(vm, "answer = 42")
{:ok, %{"value" => false}} = Kettlecorn.eval(vm, "Map.has_key?(Map.new(binding()), :answer)")

Pass values into each evaluation with :binding:

{:ok, %{"value" => 42}} = Kettlecorn.eval(vm, "x * y", binding: %{x: 6, y: 7})

An exception in evaluated code returns an error result. The VM keeps running:

{:error, %{"kind" => "error", "message" => message}} = Kettlecorn.eval(vm, ~S|raise "boom"|)
IO.puts(message)

Isolation

The guest sees a private copy of the runtime's file system. By default it has no network, can't start OS processes, can't load native code, and doesn't inherit the host's environment variables. Denied operations return error tuples or raise exceptions; environment variables that weren't passed to the guest return nil. The VM keeps running:

{:ok, %{"value" => {:error, :enoent}}} =
  Kettlecorn.eval(vm, ~S<File.read("/etc/passwd")>)

{:ok, %{"value" => {:error, :eacces}}} =
  Kettlecorn.eval(vm, ~S<:gen_tcp.connect({1, 1, 1, 1}, 80, [], 2_000)>)

{:error, %{"kind" => "error"}} = Kettlecorn.eval(vm, ~S<System.cmd("ls", [])>)

{:ok, %{"value" => nil}} = Kettlecorn.eval(vm, ~S<System.get_env("PATH")>)

The host file is absent (:enoent), socket access is denied (:eacces), starting a command raises, and the host's PATH is absent (nil).

Writes succeed, but only in the VM's copy, which is deleted when the VM stops. Halting the guest stops its VM:

{:ok, %{"value" => "notes"}} =
  Kettlecorn.eval(vm, ~S<File.write!("/tmp/notes", "notes"); File.read!("/tmp/notes")>)

{:error, {:vm_down, :normal}} =
  Kettlecorn.run("System.halt(0)", max_fuel: 50_000_000_000, max_lifetime: 10_000)

network: true and http: true grant sockets and wasi:http. They're all or nothing: Kettlecorn has no host allowlist, so a VM with a grant can reach anything the machine can. The network notebook shows both.

Limits

An evaluation that runs past its :timeout is killed. The evaluator also traces its descendants and attempts to kill them. The VM survives:

{:error, %{"kind" => "timeout"}} =
  Kettlecorn.eval(vm, "Stream.repeatedly(fn -> 1 end) |> Stream.run()", timeout: 500)

{:ok, %{"value" => :still_here}} = Kettlecorn.eval(vm, ":still_here")

Guest code can disable tracing, so evaluation cleanup is best effort. Use VM limits to bound untrusted code.

The VM as a whole has limits too: :max_memory (bytes of WebAssembly memory), :max_lifetime (wall-clock milliseconds) and :max_fuel (CPU, in Wasmtime fuel units). These limits can stop a VM without affecting the others. Here a separate, unlinked VM runs out of memory:

{:ok, small} =
  Kettlecorn.start(
    max_memory: 128 * 1024 * 1024,
    max_fuel: 100_000_000_000,
    max_lifetime: 30_000
  )

{:error, {:vm_down, reason}} =
  Kettlecorn.eval(small, ~S|Enum.map(1..100, fn _ -> :binary.copy("x", 10_000_000) end)|,
    timeout: 30_000
  )

reason

Stop the VM

Modules, processes, ETS tables, and files persist between evaluations. Give mutually untrusted tenants separate VMs. Stop a VM when you have finished:

Kettlecorn.stop(vm)

Next steps