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
4 changes: 4 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -58,6 +58,10 @@ jobs:
- run: cargo clippy --all-targets
- run: cargo test --lib
- run: cargo test --bins
# 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
- 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.
# Only a clean tree after the run catches it.
Expand Down
12 changes: 12 additions & 0 deletions Cargo.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

1 change: 1 addition & 0 deletions Cargo.toml
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
[workspace]
members = [".", "crates/sandbox"]
# Standalone workspace root. The crate previously inherited version/edition from
# a parent workspace that does not exist, so cargo failed while parsing the
# manifest, before it could even look at the source.
Expand Down
20 changes: 20 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -740,6 +740,26 @@ confined only when named; the operator's own `/bg` jobs at the REPL are never
sandboxed. Where a mode cannot be applied, the command runs unconfined and the
trace says which.

### `sbx`: the same sandbox for any agent

`crates/sandbox` builds `sbx`, a standalone sandbox that doesn't depend on
incode. It runs any command, whether an agent CLI, a test suite or Insi's
workers, under one policy file:
- writable roots, plus paths hidden even from reading (`deny_read`);
- network `allow`, `deny`, or an allowlisting proxy by host name;
- the agent-session and `GIT_DIR` variables stripped;
- CPU, memory, file-size and wall-clock limits.

It refuses a policy the machine cannot enforce in full instead of running
with less. To confine a whole incode run:

```sh
sbx run -w . -w ~/.claude -w ~/.claude.json -w ~/.incode --wall 1800 -- incode -t "…"
```

Details, the policy format and what each OS enforces are in
[`crates/sandbox/README.md`](crates/sandbox/README.md).

## Incord Memory integration

Every part is optional and fails open, except the owner channel, which fails
Expand Down
32 changes: 32 additions & 0 deletions crates/sandbox/Cargo.toml
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
[package]
name = "incord-sandbox"
version = "0.1.0"
edition = "2021"
rust-version = "1.88"
license = "Apache-2.0"
description = "Run any command - an agent CLI, a test suite, a tool call - under one policy file: filesystem, network, environment and resource limits"
repository = "https://github.com/incordai/Incode"
keywords = ["sandbox", "landlock", "seatbelt", "agents", "security"]
categories = ["command-line-utilities", "os"]

[lib]
name = "incord_sandbox"
path = "src/lib.rs"

[[bin]]
name = "sbx"
path = "src/main.rs"

[dependencies]
serde = { version = "1", features = ["derive"] }
serde_json = "1"
toml = "1"

[target.'cfg(unix)'.dependencies]
libc = "0.2"

[target.'cfg(target_os = "linux")'.dependencies]
landlock = "=0.4.7"

[dev-dependencies]
tempfile = "3"
170 changes: 170 additions & 0 deletions crates/sandbox/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,170 @@
# sbx: one sandbox for any agent

`sbx` runs a command under one policy: what it may write, what it may read,
which hosts it may reach, which environment it starts with, and how much it
may use. It works with any agent CLI (`claude`, `codex`, `incode`, `aider`,
…), with a test suite a harness runs, or with a single tool call. The policy
means the same thing on every platform. Where a platform cannot enforce part
of it, `sbx` says so before anything runs. By default it then refuses
instead of running with less.

```sh
# Write only in this project; network only to the package registry; 30 minutes.
sbx run -w . --allow-host crates.io --allow-host '*.crates.io' --wall 1800 -- cargo build

# An agent CLI confined to its workspace, with a folder it must not see.
sbx run -w . -w ~/.claude -w ~/.claude.json --deny-read ../private-checks -- claude -p "fix the failing test"

# What would this machine enforce?
sbx doctor
sbx check --policy agent.toml --json
```

It's a crate in the incode repository for now and doesn't depend on incode.
It builds to one binary, `sbx`, and a library, `incord_sandbox`.

## The policy file

```toml
[fs]
mode = "workspace-write" # off | read-only | workspace-write
write = ["."] # writable roots
deny_read = ["../private"] # hidden: not even readable

[network]
mode = "proxy" # allow | deny | proxy
allow = ["crates.io", "*.crates.io:443", "registry.npmjs.org"]
allow_private = false # may an allowed name resolve to a private address?

[env]
inherit = "all" # all | none (essentials kept)
pass = ["ANTHROPIC_API_KEY"] # kept when inherit = "none"
remove = ["AWS_*"] # a trailing * matches a prefix
strip_agent_session = true # CLAUDECODE, CLAUDE_CODE_SESSION*, ... (default)
strip_git_redirects = true # GIT_DIR, GIT_WORK_TREE, ... (default)
set = { CI = "1" }

[limits]
wall_secs = 1800 # the whole process group is killed
cpu_secs = 1200 # per process
memory_mb = 4096 # address space per process
file_size_mb = 1024
open_files = 4096
```

Every flag of `sbx run` has a policy key. Flags apply on top of `--policy`.
An unknown key is an error, so a misspelt `wirte` can't silently do nothing.

## What is enforced, and how

| | Linux | macOS | Windows |
|---|---|---|---|
| filesystem: write | Landlock (5.13+) | Seatbelt | **not yet** |
| filesystem: `deny_read` | Landlock | Seatbelt | **not yet** |
| network: `deny` | Landlock TCP (6.7+) + seccomp for every other socket | Seatbelt | **not yet** |
| network: `proxy` | Landlock: TCP only to the proxy's port; seccomp as for `deny` | Seatbelt: outbound only to the proxy | **not yet** |
| limits | `setrlimit` + wall clock | `setrlimit` + wall clock | wall clock |
| environment | yes | yes | yes |

- **Every process it starts.** The confinement is applied in a helper
process just before it execs the command. Children inherit it, and it
can't be widened again (`no_new_privs` is set).
- **A private temp directory.** Each run gets one (`TMPDIR`, `TMP`,
`TEMP`), removed afterwards. The shared `/tmp` is not writable.
- **Sockets Landlock does not see.** Landlock covers TCP only. Under `deny`
and `proxy` a seccomp filter makes `socket()` fail (`EACCES`) for anything
but Unix sockets, netlink and plain TCP: UDP, ICMP, raw and packet
sockets, SCTP and MPTCP (Landlock's TCP rules do not apply to them: an
MPTCP connect got through `deny` on Linux 6.18), and other families such
as `AF_VSOCK`.
- So under `deny`, DNS is blocked too: a lookup fails. Under `proxy` the
command never needed DNS; the proxy resolves names.
- Netlink stays: `getaddrinfo` and `ip` read the machine's addresses and
routes through it. A command can see the host's interfaces; changing
them needs a capability it does not have, and nothing sent on netlink
leaves the machine.
- `io_uring`, which can open sockets past a seccomp filter, is refused
(`EPERM`; runtimes fall back). On x86-64 the 32-bit syscall entry points
are filtered as well.
- The filter knows x86-64 and aarch64. On any other architecture none is
installed, the network is reported **not enforced**, and strict mode
refuses.
- **The proxy.** `proxy` mode runs an allowlisting HTTP proxy in the
unconfined parent and points the command at it (`HTTP(S)_PROXY`).
- It sees host names, not content: TLS is tunnelled with `CONNECT`.
- It resolves each name once and connects to the checked address, so DNS
can't redirect an allowed name to a private address or the cloud
metadata service. Turn this check off with `allow_private`.
- When `sbx` itself runs behind an HTTP proxy, allowed requests are chained
through it, and that proxy does the resolving.
- **`deny_read`.** Landlock only grants, so a hidden path is carved out by
granting its siblings, level by level from `/`.
- Directories *above* a hidden path can't be listed (`ls /` is refused);
files beneath them can still be read.
- A symlink that leads into or above a hidden path isn't granted.
- Not covered: a hard link to a hidden file made elsewhere beforehand, or
the same directory mounted a second time.
- **Process lifetime.**
- With a wall-clock limit, the command gets its own process group. The
limit kills all of it, and `SIGINT`/`SIGTERM`/`SIGHUP` sent to `sbx` are
passed on.
- If `sbx` is killed with `SIGKILL`, a supervisor kills the group too.
- Without a limit, the command stays in the caller's process group, so the
caller's own group kill reaches it.

**Known limits:**
- A name lookup a local daemon answers over a Unix socket still works
under `deny`: with `nss-resolve` (systemd-resolved) or `nscd` in
`/etc/nsswitch.conf`, the name reaches the resolver and the answer comes
back. Plain `files dns` setups fail the lookup.
- Landlock matches network ports, not addresses. Under `proxy` the command
could connect to *any* host on the proxy's (random, high) port.
- On macOS the profile is generated and unit-tested, but this crate's
network and `deny_read` clauses have not yet been run on a Mac.

## Exit codes

| code | meaning |
|---|---|
| the command's | it ran |
| 124 | the wall-clock limit killed it |
| 125 | `sbx` refused (strict, or a bad policy) or failed |
| 126 / 127 | the command could not be run / found |
| 128 + n | it was killed by signal n |

## Using it from Rust

```rust
use incord_sandbox::{Policy, Sandbox};

fn main() {
incord_sandbox::enter_if_requested(); // first: the helper is this binary
let mut policy = Policy::workspace("/path/to/worktree");
policy.fs.deny_read.push("/path/to/hidden-tests".into());
policy.limits.wall_secs = Some(1800);
let outcome = Sandbox::new(policy)
.run("cargo", &["test".into()], std::path::Path::new("/path/to/worktree"))
.expect("runs");
std::process::exit(outcome.code());
}
```

`Sandbox::command` returns the `Command` and a guard instead, for a caller
that sets its own pipes. Keep the guard alive until the command exits: it
holds the proxy and the temp directory.

## Tests

`cargo test -p incord-sandbox` runs:
- the unit tests (policy, environment, allowlist, Seatbelt profile);
- on Linux, escape tests through the real binary: writes outside the root,
symlinks, hard links, renames, `/proc/self/root`, child processes, reading
a hidden path, connecting and binding under `deny`, UDP and raw sockets
and DNS under `deny` and `proxy`, bypassing the proxy, the wall limit and
`SIGKILL` cleanup, limits and exit codes;
- on macOS, the same escapes against Seatbelt where they apply (writes,
symlinks, children, read-only, `deny_read`, TCP under `deny`, the proxy,
the environment, the wall limit).

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