Skip to content
23 changes: 23 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -189,11 +189,34 @@ any of them with `mix run examples/<name>.exs`:
walkthrough of the embedding patterns.
- The [`~LUA` sigil and Mix tasks](https://github.com/tv-labs/lua/blob/main/guides/mix_tasks.md)
guide covers compile-time validation and tooling.
- The [Security and sandboxing](guides/sandboxing.md) guide covers the sandbox,
allocation guards, recursion limits, and bounding CPU and memory.

> #### Lua the Elixir library vs Lua the language {: .info}
> When referring to this library, `Lua` is stylized as a link. References to
> Lua the language are in plaintext and not linked.

## Security and sandboxing

`Lua` is built to run untrusted scripts. By default, `Lua.new/1` installs
a sandbox that blocks the dangerous standard-library paths (`io`, `file`,
`os.execute`/`exit`/`getenv`, `package`, `require`, `load`, …), and the VM
guards against allocation-bomb denial-of-service by refusing oversized
`string.rep`, `table.unpack`/`concat`/`move`, and string concatenations
before they allocate.

```elixir
# os.exit is sandboxed by default — calling it raises (catchable)
iex> {[false, message], _} = Lua.eval!(Lua.new(), "return pcall(os.exit)")
iex> message =~ "sandboxed"
true
```

Capability sandboxing (`:sandboxed`, `:exclude`, `Lua.sandbox/2`),
recursion limits (`:max_call_depth`), the built-in allocation guards, and
the host-level pattern for bounding CPU time and total memory are all
covered in the [Security and sandboxing](guides/sandboxing.md) guide.

## Compatibility and credits

`Lua` started as an ergonomic Elixir wrapper around Robert Virding's
Expand Down
245 changes: 245 additions & 0 deletions guides/sandboxing.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,245 @@
# Security and sandboxing

`Lua` is designed to run untrusted scripts, but running untrusted code
safely takes more than calling `Lua.eval!/2`. There are three layers to
think about, from "what a script is allowed to *do*" down to "how much it
is allowed to *consume*":

1. **Capability sandboxing** — which standard-library functions the
script can call (filesystem, OS, module loading, …).
2. **Resource limits** — bounds on a single script's allocations and
recursion, enforced inside the VM.
3. **Host-level isolation** — wall-clock time and total memory, which the
VM cannot enforce on its own and which are *your* responsibility.

This guide covers all three.

## Capability sandboxing

### The default deny-list

`Lua.new/1` installs a sandbox by default. A sandboxed path is replaced
with a function that raises when called, so the script can still *refer*
to it but cannot *use* it. The defaults block the dangerous corners of
the standard library:

* **Filesystem / IO** — the whole `io` table (`io.open`, `io.read`,
`io.write`, `io.lines`, `io.popen`, …) and `file`
* **Operating system** — `os.execute`, `os.exit`, `os.getenv`,
`os.remove`, `os.rename`, `os.tmpname`
* **Code loading** — `package`, `require`, `load`, `loadfile`,
`loadstring`, `dofile`

Everything else — `string`, `table`, `math`, `utf8`, the `debug`
library, metatables, coroutity-free control flow — remains available.

```elixir
# os.exit is sandboxed by default
{[false, message], _} =
Lua.eval!(Lua.new(), "return pcall(os.exit)")

message =~ "sandboxed"
#=> true
```

### Adding to the sandbox

Pass `:sandboxed` to replace the default list with your own set of paths.
This is an *allow-by-default* model: anything not listed stays callable.

```elixir
# Block string.rep specifically, on top of nothing else
lua = Lua.new(sandboxed: [[:string, :rep]])
```

### Removing from the sandbox

If you want the defaults *minus* a few entries, use `:exclude` to punch
holes in the default deny-list rather than re-listing everything.

```elixir
# Keep all the defaults, but allow `require`
lua = Lua.new(exclude: [[:require], [:package]])
```

To disable capability sandboxing entirely (for trusted code only), pass
an empty list:

```elixir
lua = Lua.new(sandboxed: [])
```

### Sandboxing a single path

`Lua.sandbox/2` sandboxes one path on an existing VM, which is handy when
building a configuration up in steps:

```elixir
lua =
Lua.new(sandboxed: [])
|> Lua.sandbox([:os, :exit])
|> Lua.sandbox([:os, :execute])
```

## Resource limits (always on)

Several standard-library functions take a size or count argument that an
attacker can inflate to force a huge allocation — the classic
`string.rep("x", 1e15)` "allocate until the host dies" attack. `Lua`
computes the resulting size *before* allocating and raises a catchable
error when it would be unreasonable, so the attempt fails in microseconds
instead of exhausting memory.

These guards are always on and need no configuration. They cover:

| Operation | Guard | Error (catchable with `pcall`) |
| :-------- | :---- | :----------------------------- |
| `string.rep`, the `..` operator | result larger than ~256 MiB | `resulting string too large` |
| `string.format` width/precision | field wider than 99 | `invalid conversion` |
| `table.unpack` | more than 10M results | `too many results to unpack` |
| `table.concat`, `table.move` | range wider than 10M | `range too large` |
| `load` (when enabled) | reader returns > ~256 MiB total | `resulting string too large` |

```elixir
{[false, message], _} =
Lua.eval!(Lua.new(), ~s|return pcall(string.rep, "x", 1e15)|)

message =~ "resulting string too large"
#=> true
```

Because these surface as ordinary Lua errors, a script can even recover
from them with `pcall`.

## Call depth

By default the VM places no limit on call depth, so deeply recursive or
runaway-recursive scripts can grow the host process stack until it
crashes. Set `:max_call_depth` to bound it; exceeding the limit raises a
catchable `"stack overflow"`:

```elixir
lua = Lua.new(max_call_depth: 200)

{[false, message], _} =
Lua.eval!(lua, "local function f() return f() end return pcall(f)")

message =~ "stack overflow"
#=> true
```

> #### Tail calls count {: .info}
> This VM does not implement tail-call optimization, so a call in tail
> position (`return f(x)`) consumes a frame like any other. A finite
> `:max_call_depth` therefore also bounds tail recursion — including
> loops that PUC-Lua would run forever. Leave the default `:infinity`
> if you rely on unbounded tail recursion.

## Limiting CPU time and total memory

The VM has **no internal wall-clock timeout** and does **not** cap the
host process's total memory. A script can still spin forever
(`while true do end`) or accumulate memory in ways the per-operation
guards above don't catch (for example, growing a table in a loop). These
limits have to be enforced by the BEAM, around the call.

Run untrusted scripts in a **separate, monitored process** with both a
timeout and a heap ceiling. The key is to keep the wall-clock timeout and
the memory kill on **separate `receive` arms** so the two failure modes
stay distinguishable:

```elixir
defmodule SafeLua do
# ~64 MB, in heap words (8 bytes/word on a 64-bit VM).
@heap_words 8_000_000
@timeout_ms 1_000

def run(lua, source) do
parent = self()

# Trap exits so the worker dying — whether it finishes, is killed by
# the memory ceiling, or we tear it down on timeout — arrives as a
# message instead of crashing the caller. Restore the flag afterwards.
prev_trap = Process.flag(:trap_exit, true)

worker =
spawn_link(fn ->
# CRITICAL: include_shared_binaries: true. Without it, max_heap_size
# counts only the process heap, NOT off-heap reference-counted
# binaries (>64 bytes) — so a binary bomb would slip past the limit.
# This option requires OTP 27+.
Process.flag(:max_heap_size, %{
size: @heap_words,
kill: true,
error_logger: false,
include_shared_binaries: true
})

send(parent, {:result, Lua.eval!(lua, source)})
end)

try do
receive do
{:result, {result, _lua}} ->
{:ok, result}

# Worker hit the memory ceiling: max_heap_size kills it with
# `:killed`, the only abnormal exit we attribute to the limit.
{:EXIT, ^worker, :killed} ->
{:error, :memory_limit}

# Any other abnormal worker exit is an unrelated crash.
{:EXIT, ^worker, reason} ->
{:error, reason}
after
@timeout_ms ->
Process.exit(worker, :kill)
{:error, :timeout}
end
after
Process.flag(:trap_exit, prev_trap)
end
end
end
```

Two details make this robust:

* **Separate `receive` arms for timeout and `:killed`.** A wall-clock
timeout fires the `after` clause and reports `:timeout`; a memory kill
arrives as `{:EXIT, worker, :killed}` and reports `:memory_limit`. The
tempting `Task.yield(task, @timeout_ms) || Task.shutdown(task,
:brutal_kill)` shape collapses the two: `brutal_kill` on a timeout also
exits the worker with `:killed`, so a CPU-bound infinite loop would be
mislabeled a memory limit.
* **`trap_exit` + `spawn_link`** turns the worker's exit into a message
the caller can match on, instead of letting the kill propagate and
crash the caller. Restoring the previous `trap_exit` flag in the
`after` block leaves the caller's state untouched.
* **`include_shared_binaries: true`** is what makes the memory ceiling
actually work for the binary-allocation attacks. Large Lua strings
become off-heap BEAM binaries; without this flag they are not counted
toward `max_heap_size` and the kill never fires.

> #### max_heap_size is a backstop, not a precise fence {: .warning}
> The heap limit is checked at garbage-collection time, so a single
> enormous allocation can momentarily exceed it before the kill lands.
> The VM's built-in per-operation guards (above) are the deterministic
> defense; `max_heap_size` catches the accumulation cases they can't see.

## Putting it together

A typical configuration for running untrusted scripts combines all three
layers — the default sandbox, a call-depth bound, and a process wrapper
for time and memory:

```elixir
lua = Lua.new(max_call_depth: 200)

SafeLua.run(lua, untrusted_source)
```

The default sandbox blocks the OS/filesystem/loader surface, the built-in
guards turn allocation bombs into catchable errors, `:max_call_depth`
bounds recursion, and `SafeLua.run/2` bounds wall-clock time and total
memory — with the host process surviving every one of those failures.
11 changes: 11 additions & 0 deletions lib/lua/vm/dispatcher.ex
Original file line number Diff line number Diff line change
Expand Up @@ -23,11 +23,18 @@ defmodule Lua.VM.Dispatcher do
alias Lua.Compiler.Prototype
alias Lua.VM.Executor
alias Lua.VM.InternalError
alias Lua.VM.Limits
alias Lua.VM.Numeric
alias Lua.VM.RuntimeError
alias Lua.VM.State
alias Lua.VM.Table
alias Lua.VM.Value

# Mirror of the interpreter's concat ceiling, inlined as a compile-time
# constant so the binary-binary fast path stays a single comparison. See
# `Lua.VM.Executor.concat_checked/2` for the rationale.
@max_string_bytes Limits.max_string_bytes()

# Opcode tags. These must stay in lockstep with `Lua.Compiler.Bytecode`.
# The module-attribute form lets each case branch match a constant
# integer, which the BEAM collapses to a jump table.
Expand Down Expand Up @@ -1096,6 +1103,10 @@ defmodule Lua.VM.Dispatcher do
right = :erlang.element(b + 1, regs)

if is_binary(left) and is_binary(right) do
if byte_size(left) + byte_size(right) > @max_string_bytes do
raise RuntimeError, value: "resulting string too large"
end

regs = :erlang.setelement(dest + 1, regs, left <> right)
dispatch(code, pc + 1, regs, upvalues, proto, state, cont, frames)
else
Expand Down
27 changes: 23 additions & 4 deletions lib/lua/vm/executor.ex
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@ defmodule Lua.VM.Executor do

alias Lua.VM.Dispatcher
alias Lua.VM.InternalError
alias Lua.VM.Limits
alias Lua.VM.Numeric
alias Lua.VM.RuntimeError
alias Lua.VM.State
Expand Down Expand Up @@ -419,7 +420,7 @@ defmodule Lua.VM.Executor do
src = proto.source

try_binary_metamethod("__concat", left, right, state, fn ->
concat_coerce(left, 0, src) <> concat_coerce(right, 0, src)
concat_checked(concat_coerce(left, 0, src), concat_coerce(right, 0, src))
end)
end

Expand Down Expand Up @@ -1350,12 +1351,12 @@ defmodule Lua.VM.Executor do
# also concatenate without metamethods.
cond do
is_binary(left) and is_binary(right) ->
regs = put_elem(regs, dest, left <> right)
regs = put_elem(regs, dest, concat_checked(left, right))
do_execute(rest, regs, upvalues, proto, state, cont, frames, line)

(is_binary(left) or is_number(left)) and (is_binary(right) or is_number(right)) ->
src = proto.source
result = concat_coerce(left, line, src) <> concat_coerce(right, line, src)
result = concat_checked(concat_coerce(left, line, src), concat_coerce(right, line, src))
regs = put_elem(regs, dest, result)
do_execute(rest, regs, upvalues, proto, state, cont, frames, line)

Expand All @@ -1364,7 +1365,7 @@ defmodule Lua.VM.Executor do

{result, new_state} =
try_binary_metamethod("__concat", left, right, state, fn ->
concat_coerce(left, line, src) <> concat_coerce(right, line, src)
concat_checked(concat_coerce(left, line, src), concat_coerce(right, line, src))
end)

regs = put_elem(regs, dest, result)
Expand Down Expand Up @@ -2156,6 +2157,24 @@ defmodule Lua.VM.Executor do
value_type: value_type(value)
end

# `..` builds a new binary on every step. A doubling loop (`s = s .. s`)
# reaches sizes where a single concat allocates more than the heap limit
# in one BIF call — faster than the GC-time `max_heap_size` check can
# react. Guard the size deterministically here, matching the Layer A
# stdlib checks, so the loop fails with a catchable error long before it
# threatens the host. `byte_size/1` is O(1), so this is cheap on the hot
# path. Compile-time constant; no per-call dispatch into `Limits`.
@max_string_bytes Limits.max_string_bytes()

@compile {:inline, concat_checked: 2}
defp concat_checked(left, right) when byte_size(left) + byte_size(right) <= @max_string_bytes do
left <> right
end

defp concat_checked(_left, _right) do
raise RuntimeError, value: "resulting string too large"
end

# ── Metamethod support ─────────────────────────────────────────────────────

@metamethod_chain_limit 200
Expand Down
Loading
Loading