Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
11 changes: 11 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -84,6 +84,17 @@ jobs:
# The standalone sandbox (`sbx`). Its escape tests run on Linux and
# macOS, and skip, saying so, where the OS cannot enforce what they check.
- run: cargo clippy -p incord-sandbox --all-targets -- -D warnings
# Network deny natively on Windows (layer 2): the offline account and
# its firewall filters. The runner is an administrator. Without this
# the Windows network tests skip, saying so.
- name: sbx setup-windows
if: runner.os == 'Windows'
run: cargo run -p incord-sandbox --bin sbx -- setup-windows
- name: sbx doctor (after setup-windows)
if: runner.os == 'Windows'
env:
SBX_BACKEND: native
run: cargo run -p incord-sandbox --bin sbx -- doctor
- run: cargo test -p incord-sandbox
# A test that writes outside its temp dir lands in the checkout — a
# Windows drive path is RELATIVE on Linux and macOS — and passes anyway.
Expand Down
9 changes: 8 additions & 1 deletion TESTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ an email (`git config --global user.name ...`, `user.email ...`).
|---|---|---|
| rust | `cargo fmt --all -- --check` · `cargo clippy --all-targets -- -D warnings` · `cargo test --lib` · `cargo test --bins` | incode itself: about 2,100 library and 50 binary tests |
| rust | `cargo test --test sbx_engine` | Real shell commands run under `sandbox_engine = "sbx"`: a write outside the workspace refused (with an unconfined control), a planted git hook undone, `GIT_DIR` stripped. Linux; says it skipped elsewhere |
| sbx | `cargo clippy -p incord-sandbox --all-targets -- -D warnings` · `cargo test -p incord-sandbox` | The standalone sandbox: escape tests per OS, the MCP server, `.git` protection, WSL path translation |
| sbx | `cargo clippy -p incord-sandbox --all-targets -- -D warnings` · `cargo test -p incord-sandbox` | The standalone sandbox: escape tests per OS, the MCP server, `.git` protection, WSL path translation. On Windows CI, `sbx setup-windows` runs first so the native network-deny tests run |
| python | `python3 -m unittest discover sdk/python/tests` | The Python SDK, against a fake incode |
| ts | `cd sdk/typescript && npm install && npm test` | The TypeScript SDK, against the same fake |
| vscode | `cd editors/vscode && npm install && npm run compile && npm test` | The VS Code extension's ACP client, against a fake agent |
Expand All @@ -54,6 +54,13 @@ exit codes, the MCP server) and writes `sbx-windows-report.txt`. These need
real Windows: Wine cannot check Windows' own security. Nothing is installed
and nothing outside a temp folder is changed.

The network tests (deny and proxy natively: TCP, UDP, the offline account's
grants, concurrent runs, the proxy's allowlist) run only where
`sbx setup-windows` has been run, from an elevated prompt (it makes a local
account and firewall filters; `sbx setup-windows --remove` undoes it);
elsewhere they print SKIPPED. CI runs the setup on `windows-latest` before
`cargo test -p incord-sandbox`, so they always run there.

The whole Rust suite runs on Windows too (`cargo test --lib`, `cargo test --bins`).

## Live tests, off by default
Expand Down
16 changes: 13 additions & 3 deletions crates/sandbox/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -26,17 +26,27 @@ toml = "1"
libc = "0.2"

# The native Windows sandbox (`src/windows`): a write-restricted token, an
# ACE per writable root, and a job object. The same version and features incode
# itself already resolves (windows-sys 0.61.2 is in Cargo.lock), so nothing new
# is downloaded or linked.
# ACE per writable root, and a job object; and for network deny (layer 2,
# `sbx setup-windows`) a local account, DPAPI for its password and Windows
# Filtering Platform filters. The same windows-sys incode itself already
# resolves (0.61.2 is in Cargo.lock), so nothing new is downloaded; the extra
# features only add bindings.
[target.'cfg(windows)'.dependencies]
windows-sys = { version = "0.61", features = [
"Win32_Foundation",
"Win32_NetworkManagement_NetManagement",
"Win32_NetworkManagement_WindowsFilteringPlatform",
"Win32_Security",
"Win32_Security_Authorization",
"Win32_Security_Cryptography",
"Win32_Storage_FileSystem",
"Win32_System_Console",
"Win32_System_Environment",
"Win32_System_JobObjects",
"Win32_System_Registry",
"Win32_System_Rpc",
"Win32_System_Threading",
"Win32_System_WindowsProgramming",
] }

[target.'cfg(target_os = "linux")'.dependencies]
Expand Down
150 changes: 137 additions & 13 deletions crates/sandbox/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -61,8 +61,8 @@ An unknown key is an error, so a misspelt `wirte` can't silently do nothing.
|---|---|---|---|
| filesystem: write | Landlock (5.13+) | Seatbelt | write-restricted token + a per-run ACE on each root |
| filesystem: `deny_read` | Landlock | Seatbelt | **not enforced** (WSL2 does it) |
| network: `deny` | Landlock TCP (6.7+) + seccomp for every other socket | Seatbelt | **not enforced** (WSL2 does it) |
| network: `proxy` | Landlock: TCP only to the proxy's port; seccomp as for `deny` | Seatbelt: outbound only to the proxy | **not enforced** (WSL2 does it) |
| network: `deny` | Landlock TCP (6.7+) + seccomp for every other socket | Seatbelt | after `sbx setup-windows`: runs as an offline account WFP filters cut off; else **not enforced** (WSL2 does it) |
| network: `proxy` | Landlock: TCP only to the proxy's port; seccomp as for `deny` | Seatbelt: outbound only to the proxy | after `sbx setup-windows`: the offline account may reach only the proxy's loopback ports; else **not enforced** (WSL2 does it) |
| `.git/hooks`, `.git/config` | snapshotted, put back after the run | Seatbelt refuses the write | snapshotted, put back after the run |
| signals, abstract Unix sockets | Landlock scopes (6.12+): only within the sandbox | Seatbelt default | the token cannot open other processes for writing (measured by incode) |
| Windows programs (inside WSL2) | interop interpreter and sockets hidden, `WSL_INTEROP` removed, vsock refused | n/a | n/a |
Expand Down Expand Up @@ -181,16 +181,19 @@ and forwards it to the Linux `sbx` inside WSL2 when it doesn't (see
`SBX_NATIVE=1`, the older switch, still means `native`. `sbx doctor` shows
what native enforces and whether WSL2 forwarding is available.

So a policy that confines files, environment and time runs natively, and
one that asks for `network: deny`/`proxy` or `deny_read` goes to WSL2.
So a policy that confines files, environment and time runs natively. One
that asks for `network: deny`/`proxy` runs natively too once
[`sbx setup-windows`](#network-natively-sbx-setup-windows) has been run on
the machine, and goes to WSL2 otherwise. `deny_read` always goes to WSL2.
`sbx mcp` follows the same rule from its ceilings: with `--net allow` it
runs natively, with `--net deny` (its default) or `proxy` in WSL2.
runs natively, with `--net deny` (its default) or `proxy` natively after
the setup and in WSL2 without it.

### Native

Ported from incode's own Windows sandbox, whose authors measured it on
Windows. **This crate's port has not run on Windows yet:** its tests
(`tests/escape_windows.rs`) run on the `windows-latest` CI runner.
Windows. This crate's port is checked by its tests
(`tests/escape_windows.rs`) on the `windows-latest` CI runner.

- **Writes.** The command runs under a *write-restricted token*: it reads
anything its user can, but writes only where the user may **and** one of
Expand Down Expand Up @@ -224,10 +227,11 @@ Windows. **This crate's port has not run on Windows yet:** its tests
- **Exit codes** are passed through whole (32 bits).

**Not enforced natively, and why:**
- **Network.** No token restricts the network (incode measured TCP, HTTP and
HTTPS all working under it). Only an AppContainer does, and an AppContainer
reads only what is granted to it: the workspace, your toolchains, your
profile. `deny` and `proxy` go to WSL2 (`auto`) or are refused (`native`).
- **Network, until `sbx setup-windows` has run.** No token restricts the
network (incode measured TCP, HTTP and HTTPS all working under it). Only
an AppContainer does, and an AppContainer reads only what is granted to
it: the workspace, your toolchains, your profile. So without the setup
below, `deny` and `proxy` go to WSL2 (`auto`) or are refused (`native`).
- **`deny_read`.** A write-restricted token checks its restricting SIDs only
for writes, so no ACE can hide a path from the sandbox alone. Denying your
own SID would hide it from you everywhere. A fully restricted token would
Expand All @@ -243,6 +247,124 @@ Windows. **This crate's port has not run on Windows yet:** its tests
- **Grants are visible.** While a run lasts, every object under a root
carries the run's ACE, and the grant and revoke cost time on large trees.

### Network natively: `sbx setup-windows`

The Windows Filtering Platform can block a connection by the *user* who
makes it. So, the way OpenAI Codex's Windows sandbox does it
(`codex-rs/windows-sandbox-rs`), a one-time setup makes a local account
that the firewall cuts off, and `deny`/`proxy` runs start the command as
that account. From an elevated prompt (Run as administrator), once:

```powershell
sbx setup-windows # or: ... --read C:\Users\me\.cargo --read C:\Users\me\.rustup
sbx doctor # [ok ] offline user ...
sbx run -w . --net deny -- cargo test # natively now, not in WSL2
sbx setup-windows --remove # undoes all of it
```

What it does (each step is idempotent; running it again resets the
password and re-adds each filter):

1. **An account, `sbx-offline`**, member of `Users` only (it needs `Users`
to log on locally and to read `C:\Windows` and `Program Files`; it is
taken out of `Administrators` if anyone put it there), with a random
password (256 bits) that is never shown, hidden from the sign-in screen.
2. **Its password**, DPAPI-protected with machine scope, in
`%ProgramData%\sbx\offline.conf`. The folder's ACL allows SYSTEM,
Administrators and the user who ran the setup, and nobody else: not
`Users`, so not the offline account, and not a sandboxed command. Machine
scope rather than user scope because the setup may run elevated as a
different administrator than the user who runs sandboxes; not LSA
private data because only administrators can read that back, and runs
are not elevated. The ACL is the protection; DPAPI makes the file
useless off this machine.
3. **Persistent WFP filters** for that account's SID
(`FWPM_CONDITION_ALE_USER_ID`): every outbound connection and every first
UDP/raw packet (`ALE_AUTH_CONNECT`), every inbound connection
(`ALE_AUTH_RECV_ACCEPT`), IPv4 and IPv6, loopback included, and raw ICMP
sockets (`ALE_RESOURCE_ASSIGNMENT`), all blocked. One permit outranks
them: TCP to `127.0.0.1` on ports 47600-47615 (`--proxy-ports` changes
the range), where a `proxy` run's proxy listens. WFP directly
(`FwpmFilterAdd0`, in one transaction, under fixed keys), not `netsh`.
4. `--read <DIR>` (repeatable, kept across re-runs) lets the account read a
folder: a toolchain under your profile (see *Reads* below).

At run time (unelevated), `sbx` starts its helper a second time as the
account with `CreateProcessWithLogonW`, the one call an unprivileged process
can start another user's process with (`CreateProcessAsUserW` with that
user's token needs `SeAssignPrimaryTokenPrivilege`, and
`CreateProcessWithTokenW` `SeImpersonatePrivilege`; Codex starts its command
runner the same way). That helper builds the write-restricted token from its
own token, as above, and starts the command; the job object holds both, so
limits, the wall clock, killing the tree and exit codes work as before. No
profile is loaded for the account (Codex's runner doesn't either): it would
create `C:\Users\sbx-offline`, a home every run would share. The command
gets the run's computed environment.

What changes for the command:
- **Reads.** It reads what the account may read, not what you may: system
folders, and what each run grants it (the writable roots, the folder it
starts in, the `sbx` program, its private temp directory), plus folders
granted with `--read`. A toolchain installed under your profile
(`.cargo`, `.rustup`, a per-user Python or Node) needs `--read` once.
Narrower than without network deny, never wider. One more right: the
account may *list* each folder above the current folder, up to the drive
root or `C:\Users` (names, no contents), by one ACE per folder that
nothing beneath it inherits, for the run. Windows PowerShell needs it: it
looks every part of its starting folder up in the folder above, and
without it starts at `C:\` (so `Set-Content x.txt` wrote `C:\x.txt`). So
during a run the command can see the names in, say, your profile folder
and `AppData\Local\Temp` on the way to a project under them.
- **Writes** need both the account (the token's normal check) and the run's
private SID (its restricted check), so each root gets an ACE for each.
Another run's command, also the account but with another run SID, cannot
write your run's roots. The account's ACE on a folder is shared by runs
that grant the same folder, and removed only when the last of them ends.
With `--fs off` the command is not write-restricted but is still the
account: it can write the folder it starts in and its temp directory, and
what the account itself may write.
- **`sbx` itself** must be readable by the account; it is granted per run
when you own the file (a build under your profile), and is already when
installed under `Program Files`.

**Known limits:**
- **DNS answers still come back.** Name lookups go to the DNS Client
service, which resolves on the command's behalf as `NetworkService`, as
`systemd-resolved` does on Linux; a connection to the answer is blocked.
- **SMB and WebDAV paths** (`\\host\share`) are opened by the kernel
redirector, not by the command, and are not stopped by the filters. The
account's random password authenticates nowhere else, but a server that
allows guest access would be reachable.
- **Loopback is blocked under `deny`**, including a test suite talking to a
server it started itself, and Python's `asyncio` on Windows (its event
loop wakes itself through a loopback socket pair). Use `proxy` with no
hosts, or `allow`, for those.
- **Under `proxy`** the command can reach any process listening on the
proxy port range, including another `proxy` run's proxy (with that run's
allowlist). The ports are below Windows' dynamic range, so nothing gets
one by chance.
- **Proxies the account cannot use.** Windows PowerShell 5.1's
`Invoke-WebRequest` ignores `HTTP_PROXY`, and .NET Framework sends
requests for `localhost` past any proxy; tools that honour `HTTPS_PROXY`
(`curl`, `git`, `cargo`, `npm`, `pip`) work.
- Only the user who ran the setup can use it (the record is readable by
that user alone). Another user's `sbx doctor` says so.
- The thread objects of the account's helper get the account logon's default
DACL, which is not measured yet; its process object is locked down
explicitly (`D:P(A;;GA;;;SY)(A;;0x101000;;;OW)`).

**Tested:** `tests/escape_windows.rs` runs on the `windows-latest` CI
runner after `sbx setup-windows` (CI runs it; the runner is an
administrator): TCP to a local server and to the internet refused under
`deny` with the filesystem confined, read-only and off (and allowed without
`deny`); UDP refused; writes confined, temp writable, exit codes and
"not found" passed through both helpers; the account's ACE present during a
run and gone after; two concurrent runs sharing a root (the second ending
first leaves the first its grant, and cannot write the first's other root);
the proxy letting through only its allowlist, a direct connection refused;
`sbx mcp` running a deny sandbox's PowerShell script as the account.
Without the setup these tests print SKIPPED.

### WSL2

Inside WSL2 the sandbox is the Linux one: Landlock, seccomp, the git
Expand Down Expand Up @@ -323,7 +445,7 @@ Codex, incode, or your own.

| Tool | What it does |
|---|---|
| `sandbox_create` | A private folder. Network `deny` unless the agent asks for `proxy` with hosts (or `allow`) within the server's limits. Natively on Windows only `allow` can be enforced, and asking for anything else is refused at once, saying so. |
| `sandbox_create` | A private folder. Network `deny` unless the agent asks for `proxy` with hosts (or `allow`) within the server's limits. Natively on Windows `deny` and `proxy` need `sbx setup-windows` first; without it asking for them is refused at once, saying so. |
| `sandbox_write_file` | Write a script or file, creating folders; `executable` sets 755. |
| `sandbox_run` | Run `command` (argv) or `script` (text, run with `interpreter`, default `sh`; PowerShell natively on Windows) with optional `stdin`, `cwd` and `timeout_secs`. Returns `exit_code`, `stdout`, `stderr` (64 KB each), `timed_out` and `network_refused`. |
| `sandbox_read_file` / `sandbox_list` | Read results back (256 KB at most). |
Expand Down Expand Up @@ -395,7 +517,9 @@ holds the proxy and the temp directory.
program in the current folder, the wall limit and killing `sbx` taking
the whole tree, the job's memory and CPU limits, the environment, exit
codes, refusing what native can't enforce, `auto` without WSL, `doctor`,
and `sbx mcp` run natively.
and `sbx mcp` run natively; and, where `sbx setup-windows` has run (CI
runs it first), network deny and proxy natively (see
[above](#network-natively-sbx-setup-windows)).

Each escape test skips, and says so, on a kernel that cannot enforce what
it checks.
Loading
Loading