Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

wasi: clearly document sandboxing & file system security status #50396

Closed
wants to merge 1 commit into from
Closed

wasi: clearly document sandboxing & file system security status #50396

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
45 changes: 35 additions & 10 deletions doc/api/wasi.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,11 +4,16 @@

> Stability: 1 - Experimental
<strong class="critical">The `node:wasi` module does not currently provide the
comprehensive file system security properties provided by some WASI runtimes.
Full support for secure file system sandboxing may or may not be implemented in
future. In the mean time, do not rely on it to run untrusted code. </strong>

<!-- source_link=lib/wasi.js -->

The WASI API provides an implementation of the [WebAssembly System Interface][]
specification. WASI gives sandboxed WebAssembly applications access to the
underlying operating system via a collection of POSIX-like functions.
specification. WASI gives WebAssembly applications access to the underlying
operating system via a collection of POSIX-like functions.

```mjs
import { readFile } from 'node:fs/promises';
Expand All @@ -20,7 +25,7 @@ const wasi = new WASI({
args: argv,
env,
preopens: {
'/sandbox': '/some/real/path/that/wasm/can/access',
'/local': '/some/real/path/that/wasm/can/access',
},
});

Expand All @@ -44,7 +49,7 @@ const wasi = new WASI({
args: argv,
env,
preopens: {
'/sandbox': '/some/real/path/that/wasm/can/access',
'/local': '/some/real/path/that/wasm/can/access',
},
});

Expand Down Expand Up @@ -97,6 +102,28 @@ Use [wabt](https://github.com/WebAssembly/wabt) to compile `.wat` to `.wasm`
wat2wasm demo.wat
```

## Security

<!-- YAML
added: REPLACEME
changes:
- version: REPLACEME
pr-url: https://github.com/nodejs/node/pull/50396
description: Clarify WASI security properties.
-->

WASI provides a capabilities-based model through which applications are provided
their own custom `env`, `preopens`, `stdin`, `stdout`, `stderr`, and `exit`
capabilities.

**The current Node.js threat model does not provide secure sandboxing as is
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we could mention it in the SECURITY.md file

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As far as I can tell, this is already covered by the existing thread model definition in SECURITY.md for Node.js, unless we want to explicitly call out WASI there?

present in some WASI runtimes.**

While the capability features are supported, they do not form a security model
in Node.js. For example, the file system sandboxing can be escaped with various
techniques. The project is exploring whether these security guarantees could be
added in future.

## Class: `WASI`

<!-- YAML
Expand All @@ -107,9 +134,7 @@ added:

The `WASI` class provides the WASI system call API and additional convenience
methods for working with WASI-based applications. Each `WASI` instance
represents a distinct sandbox environment. For security purposes, each `WASI`
instance must have its command-line arguments, environment variables, and
sandbox directory structure configured explicitly.
represents a distinct environment.

### `new WASI([options])`

Expand All @@ -136,9 +161,9 @@ changes:
* `env` {Object} An object similar to `process.env` that the WebAssembly
application will see as its environment. **Default:** `{}`.
* `preopens` {Object} This object represents the WebAssembly application's
sandbox directory structure. The string keys of `preopens` are treated as
directories within the sandbox. The corresponding values in `preopens` are
the real paths to those directories on the host machine.
local directory structure. The string keys of `preopens` are treated as
directories within the file system. The corresponding values in `preopens`
are the real paths to those directories on the host machine.
* `returnOnExit` {boolean} By default, when WASI applications call
`__wasi_proc_exit()` `wasi.start()` will return with the exit code
specified rather than terminating the process. Setting this option to
Expand Down