Kernel Sandboxing (cais.sandbox)¶
The sandbox subsystem provides operating system-enforced application containment using native kernel security primitives across Linux, macOS Darwin, Windows NT, OpenBSD, and FreeBSD.
Instead of forcing developers to write platform-specific code for every operating system, cais introduces a unified declarative policy engine: applications declare their access requirements (allowed filesystem paths, network permissions, child process policies, and memory execution rules), and cais automatically translates these declarations into the native kernel mechanism of the host system.
🏛️ 1. Supported Backends & Feature Matrix¶
Operating systems vary dramatically in how they implement process isolation. The table below illustrates how cais maps declarative policy fields across all supported backends:
| Backend Identifier | Name String | Native Kernel Mechanism | Filesystem Scoping | Network Restrictions | Child Process Prohibition | Dynamic Code Hardening (W^X) | Minimum OS Version |
|---|---|---|---|---|---|---|---|
CAIS_SANDBOX_BACKEND_LANDLOCK |
"landlock" |
Linux Landlock LSM + prctl |
✅ ABIs 1–5 | ✅ ABI 4+ (Linux 6.7+) | ✅ Via no_new_privs |
⚠️ Safe fallback | Linux 5.13+ |
CAIS_SANDBOX_BACKEND_SEATBELT |
"seatbelt" |
Apple Seatbelt / MAC Framework | ✅ TinyScheme SBPL | ✅ (deny network*) |
✅ (deny process-fork) |
⚠️ Via macOS SIP | Mac OS X 10.5+ (Leopard) |
CAIS_SANDBOX_BACKEND_WIN32 |
"win32" |
Process Mitigation Policies | ⚠️ Via ACLs/Tokens | ⚠️ Windows Firewall | ✅ Win 10 (1607+) | ✅ Win 8.1+ / Win 10 | Windows 8.1 / 10+ |
CAIS_SANDBOX_BACKEND_OPENBSD |
"openbsd" |
OpenBSD unveil(2) & pledge(2) |
✅ unveil paths |
✅ pledge inet |
✅ Drops proc/exec |
✅ W^X enforced by OS | OpenBSD 6.4+ |
CAIS_SANDBOX_BACKEND_CAPSICUM |
"capsicum" |
FreeBSD Capsicum Capability Mode | ✅ Capability Mode | ✅ File Descriptor Mode | ✅ Drops fork |
⚠️ Host default | FreeBSD 10.0+ |
CAIS_SANDBOX_BACKEND_NONE |
"none" |
Safe fallback stub | ⚠️ No-op | ⚠️ No-op | ⚠️ No-op | ⚠️ No-op | All other platforms |
[!IMPORTANT] The Ratchet Principle (Irreversible Enforcement): Kernel sandboxing is strictly unidirectional. Once a policy is applied via
cais_sandbox_apply()or Luasandbox.apply(), privileges can never be regained or expanded for the lifetime of that process, and all restrictions are automatically inherited by any child processes.
⚙️ 2. Constants & Enumerations¶
Backend Identifiers (cais_sandbox_backend_t)¶
Returned by cais_sandbox_backend() in C or cais.sandbox.backend() in Lua:
typedef enum {
CAIS_SANDBOX_BACKEND_NONE = 0, /* No kernel sandbox available on host */
CAIS_SANDBOX_BACKEND_LANDLOCK = 1, /* Linux Landlock LSM */
CAIS_SANDBOX_BACKEND_OPENBSD = 2, /* OpenBSD pledge(2) and unveil(2) */
CAIS_SANDBOX_BACKEND_CAPSICUM = 3, /* FreeBSD Capsicum capability mode */
CAIS_SANDBOX_BACKEND_SEATBELT = 4, /* Apple Darwin / macOS Seatbelt (sandbox_init) */
CAIS_SANDBOX_BACKEND_WIN32 = 5 /* Windows NT Process Mitigation Policies */
} cais_sandbox_backend_t;
In Lua, these constants are accessible in the cais.sandbox.backend table:
local sandbox = require("cais.sandbox")
print(sandbox.backend.LANDLOCK) -- 1
print(sandbox.backend.SEATBELT) -- 4
print(sandbox.backend.WIN32) -- 5
Filesystem Permission Flags (cais_sandbox_perm_t)¶
Bitmasks determining what operations are allowed on registered paths:
| C Constant | Lua String Equivalent | Bitmask Value | Description |
|---|---|---|---|
CAIS_SANDBOX_PERM_NONE |
"" |
0 |
No access permitted |
CAIS_SANDBOX_PERM_READ |
"r" |
1 << 0 (0x01) |
Read file contents, inspect directory entries, read symlinks |
CAIS_SANDBOX_PERM_WRITE |
"w" |
1 << 1 (0x02) |
Create, modify, overwrite, truncate, or delete files/directories |
CAIS_SANDBOX_PERM_EXEC |
"x" |
1 << 2 (0x04) |
Execute binaries or scripts located in the specified directory |
Convenience macro aliases in C: CAIS_SANDBOX_READ, CAIS_SANDBOX_WRITE, CAIS_SANDBOX_EXEC.
In Lua, combine permissions as strings: "r", "w", "rw", "rx", or "rwx".
Network Access Policy Levels (cais_sandbox_net_t)¶
Controls network socket capabilities:
| C Constant | Lua String | Value | Description |
|---|---|---|---|
CAIS_SANDBOX_NET_DEFAULT |
"default" |
0 |
Default system behavior (unrestricted) |
CAIS_SANDBOX_NET_NONE |
"none" |
1 |
Completely block network sockets and communication |
CAIS_SANDBOX_NET_LOOPBACK |
"loopback" |
2 |
Allow only local loopback traffic (127.0.0.1 / ::1) |
CAIS_SANDBOX_NET_ALL |
"all" |
3 |
Explicitly permit all outbound and inbound network communication |
Status Codes (cais_sandbox_status_t)¶
| C Constant | Lua Enum (sandbox.status) |
Value | Description |
|---|---|---|---|
CAIS_SANDBOX_OK |
sandbox.status.OK |
0 |
Policy enforced successfully |
CAIS_SANDBOX_ERROR |
sandbox.status.ERROR |
-1 |
Kernel error, invalid path, or permission denied |
CAIS_SANDBOX_UNSUPPORTED |
sandbox.status.UNSUPPORTED |
-4 |
Platform lacks a functional sandbox backend |
🛠️ 3. C89 Function Reference¶
All C APIs conform strictly to ANSI C89 (C90) and are declared in include/cais/sandbox.h.
Introspection Functions¶
cais_sandbox_backend_t cais_sandbox_backend(int *version_out);
const char *cais_sandbox_backend_name(int *version_out);
cais_bool_t cais_sandbox_is_supported(void);
cais_sandbox_backend(): Returns the active backend identifier enum and optionally writes the kernel ABI version (e.g. Landlock ABI5, or Darwin version24) toversion_out.cais_sandbox_backend_name(): Returns a static descriptive string:"landlock","seatbelt","win32","openbsd","capsicum", or"none".cais_sandbox_is_supported(): ReturnsCAIS_TRUEif a kernel-enforced sandboxing backend is available and active on the host OS.
Policy Construction & Configuration¶
cais_sandbox_policy_t *cais_sandbox_policy_create(void);
void cais_sandbox_policy_destroy(cais_sandbox_policy_t *policy);
cais_status_t cais_sandbox_policy_allow_path(
cais_sandbox_policy_t *policy,
const char *path,
int perms
);
cais_status_t cais_sandbox_policy_set_network(
cais_sandbox_policy_t *policy,
cais_sandbox_net_t net
);
cais_status_t cais_sandbox_policy_set_allow_child_processes(
cais_sandbox_policy_t *policy,
cais_bool_t allow
);
cais_status_t cais_sandbox_policy_set_allow_dynamic_code(
cais_sandbox_policy_t *policy,
cais_bool_t allow
);
cais_sandbox_policy_create(): Allocates a new empty declarative policy structure. ReturnsNULLon out-of-memory.cais_sandbox_policy_destroy(): Safely frees all memory and path rules associated with the policy.cais_sandbox_policy_allow_path(): Adds a path rule with bitwise permission flags (CAIS_SANDBOX_PERM_READ | CAIS_SANDBOX_PERM_WRITE).cais_sandbox_policy_set_network(): Configures network access policy.cais_sandbox_policy_set_allow_child_processes(): PassingCAIS_FALSEblocksfork,exec, andCreateProcess.cais_sandbox_policy_set_allow_dynamic_code(): PassingCAIS_FALSEenforces W^X memory protections (no executable heap/stack).
Policy Enforcement¶
cais_sandbox_status_t cais_sandbox_apply(
const cais_sandbox_policy_t *policy,
char *err_buf,
size_t err_cap
);
Irrevocably locks down the current process and all future descendants according to the policy.
- If
policy == NULL, applies an absolute lockdown: drops all filesystem access and drops network/process privileges where supported. - If the call fails, a human-readable diagnostic message is copied into
err_buf. - Returns
CAIS_SANDBOX_OK(0),CAIS_SANDBOX_ERROR(-1), orCAIS_SANDBOX_UNSUPPORTED(-4).
💻 4. C89 Programming Examples¶
Example 1: Hardened CLI File Processor¶
This example demonstrates a command-line tool that parses an input directory, writes results to an output directory, and locks down the process so that it cannot touch /etc, C:\Windows, or access the network:
#include <cais/sandbox.h>
#include <stdio.h>
#include <stdlib.h>
int main(int argc, char **argv) {
char err_buf[256];
int abi_ver = 0;
cais_sandbox_policy_t *policy;
cais_sandbox_status_t status;
printf("Sandbox backend: %s\n", cais_sandbox_backend_name(&abi_ver));
/* 1. Allocate declarative policy */
policy = cais_sandbox_policy_create();
if (!policy) {
fprintf(stderr, "Failed to allocate sandbox policy\n");
return 1;
}
/* 2. Configure access rules */
/* Allow reading from current working directory */
cais_sandbox_policy_allow_path(policy, ".", CAIS_SANDBOX_PERM_READ);
/* Allow reading and writing temporary scratch space */
cais_sandbox_policy_allow_path(policy, "/tmp", CAIS_SANDBOX_PERM_READ | CAIS_SANDBOX_PERM_WRITE);
/* Strictly block outbound network operations */
cais_sandbox_policy_set_network(policy, CAIS_SANDBOX_NET_NONE);
/* Forbid spawning subprocesses */
cais_sandbox_policy_set_allow_child_processes(policy, CAIS_FALSE);
/* Forbid creating executable memory (W^X) */
cais_sandbox_policy_set_allow_dynamic_code(policy, CAIS_FALSE);
/* 3. Apply and seal the sandbox */
status = cais_sandbox_apply(policy, err_buf, sizeof(err_buf));
/* Policy is no longer needed after enforcement */
cais_sandbox_policy_destroy(policy);
if (status == CAIS_SANDBOX_UNSUPPORTED) {
printf("Notice: Kernel sandbox not supported on this OS. Continuing...\n");
} else if (status != CAIS_SANDBOX_OK) {
fprintf(stderr, "Fatal sandbox error: %s\n", err_buf);
return 1;
}
printf("Process successfully confined! Performing operations safely...\n");
/* At this point, opening any file outside "." and "/tmp" will be denied by the kernel */
return 0;
}
Example 2: Absolute Lockdown Network Daemon¶
When building network services, initialize your listening sockets and load your configuration files first, then enforce complete lockdown before accepting untrusted client connections:
#include <cais/sandbox.h>
#include <stdio.h>
void enter_jail(void) {
char err_buf[256];
/* Passing NULL enforces total lockdown:
* - Linux Landlock: No paths allowed, prctl(PR_SET_NO_NEW_PRIVS)
* - macOS: TinyScheme profile denying all file operations
* - Windows: Prohibits dynamic code and subprocess creation
*/
if (cais_sandbox_apply(NULL, err_buf, sizeof(err_buf)) == CAIS_SANDBOX_ERROR) {
fprintf(stderr, "Security lockdown failed: %s\n", err_buf);
exit(1);
}
}
🌙 5. Lua API Reference & Idioms¶
In Lua, cais.sandbox provides two complementary programming styles:
1. The Object-Oriented Builder Pattern (with fluent method chaining).
2. The Declarative Table DSL (ideal for configuration-driven applications).
5.1 Object-Oriented Policy Builder¶
Created via cais.sandbox.policy([opts]). Returns a policy userdata instance.
Builder Methods:¶
-
policy:allow(path, perms)Adds a path access rule.permscan be"r","w","x","rw","rx", or"rwx". Returnsselffor chaining. -
policy:set_network(level)Sets the network policy level. Accepts"none","loopback","all", or"default". Returnsself. -
policy:deny_network()Convenience shortcut equivalent to:set_network("none"). Returnsself. -
policy:set_child_processes(allow_boolean)Allows or prohibits spawning child processes (fork,exec,CreateProcess). Returnsself. -
policy:no_child_processes()Convenience shortcut equivalent to:set_child_processes(false). Returnsself. -
policy:set_dynamic_code(allow_boolean)Allows or prohibits W^X dynamic code memory allocation. Returnsself. -
policy:no_dynamic_code()Convenience shortcut equivalent to:set_dynamic_code(false). Returnsself. -
policy:apply()Permanently enforces the policy on the current process. Returnstrueon success, orfalse, err_message, err_codeon failure. -
tostring(policy)Returns a human-readable diagnostic summary (e.g.<cais.sandbox.policy (paths=2, net=none, child_proc=false, dyn_code=false)>).
OOP Builder Example:¶
local sandbox = require("cais.sandbox")
-- Method chaining configuration:
local ok, err = sandbox.policy()
:allow(".", "r")
:allow("/tmp", "rw")
:deny_network()
:no_child_processes()
:no_dynamic_code()
:apply()
if not ok then
error("Sandbox enforcement failed: " .. tostring(err))
end
print("Sandbox successfully sealed!")
5.2 Declarative Table DSL¶
Pass a configuration table directly to cais.sandbox.apply(table):
local sandbox = require("cais.sandbox")
local ok, err, code = sandbox.apply({
paths = {
{ path = "/var/log/myapp", perm = "rw" },
{ path = "/etc/myapp", perm = "r" },
},
network = "loopback", -- "none" | "loopback" | "all" | "default"
child_processes = false, -- block fork/exec/CreateProcess
dynamic_code = false, -- block RWX memory allocation (W^X)
})
if not ok then
if code == sandbox.status.UNSUPPORTED then
print("Warning: Sandbox unsupported on this host OS.")
else
error("Security enforcement failed: " .. err)
end
end
5.3 Polymorphic cais.sandbox.apply()¶
The apply() function accepts three distinct input types:
cais.sandbox.apply(policy_userdata): Applies an OOP builder instance.cais.sandbox.apply(table): Compiles and applies a declarative table DSL.cais.sandbox.apply()/cais.sandbox.apply(nil): Enforces an immediate, zero-trust total lockdown.
🔬 6. Under the Hood: Native Platform Translation¶
Understanding how cais maps your rules to the host kernel:
1. Linux (Landlock LSM)¶
- Rule Creation: Invokes
sys_landlock_create_ruleset()configuring filesystem access masks: - Reads:
LANDLOCK_ACCESS_FS_READ_FILE | LANDLOCK_ACCESS_FS_READ_DIR - Writes:
LANDLOCK_ACCESS_FS_WRITE_FILE | LANDLOCK_ACCESS_FS_MAKE_REG | LANDLOCK_ACCESS_FS_REMOVE_FILE ... - ABI 4+ Network:
LANDLOCK_ACCESS_NET_BIND_TCP | LANDLOCK_ACCESS_NET_CONNECT_TCP - Path Addition: Opens each path with
O_PATH | O_CLOEXECand callssys_landlock_add_rule(ruleset_fd, LANDLOCK_RULE_PATH_BENEATH, ...). - Privilege Dropping: Calls
prctl(PR_SET_NO_NEW_PRIVS, 1, 0, 0, 0). - Enforcement: Enters containment via
sys_landlock_restrict_self(ruleset_fd, 0).
2. Apple macOS Darwin (Seatbelt)¶
- Dynamic TinyScheme Synthesis: Rather than static Xcode entitlements,
caisformats a Sandbox Profile Language (SBPL) Scheme script in memory: - Enforcement: Calls
sandbox_init(sbpl_script, 0, &err_msg)fromlibSystem.
3. Windows NT (Process Mitigation Policies)¶
- Dynamic Resolution: Probes
SetProcessMitigationPolicydynamically viaGetProcAddressonkernel32.dll. (Preserves compatibility with Windows 7 and XP without loader failure). - Child Processes: Enforces
ProcessChildProcessPolicy(CreateProcessreturnsERROR_ACCESS_DENIED). - Dynamic Code: Enforces
ProcessDynamicCodePolicy(prohibitsPAGE_EXECUTE_READWRITE). - Handle Checking: Enforces
ProcessStrictHandleCheckPolicy.
4. OpenBSD (unveil & pledge)¶
- Filesystem: Iterates declared paths and calls
unveil(path, perms). Callsunveil(NULL, NULL)to permanently seal path discovery. - Syscall Promises: Evaluates network and execution flags to synthesize the
pledge()promise string (e.g."stdio rpath wpath cpath inet").
5. FreeBSD (Capsicum)¶
- Capability Mode: Enters strict capability mode via
cap_enter(2). Only pre-opened file descriptors can be accessed.
⚠️ 7. Production Best Practices & Pitfalls¶
1. The Initialization Order Principle¶
[!WARNING] Always load Lua modules (
require), open necessary database handles, read system certificates, and inspect configuration files before sealing the sandbox! Once the sandbox is applied, attempts to load dynamic.soor.dlllibraries from/usr/liborC:\Windowswill be intercepted and blocked by the kernel.
-- CORRECT:
local json = require("cjson")
local socket = require("cais.socket")
local config = load_config("config.json")
-- Seal sandbox AFTER initialization
cais.sandbox.apply({ paths = { { path = "/var/data", perm = "rw" } } })
2. Testing Sandboxes in Child Processes¶
Because sandboxing is permanent and cannot be undone within a running process, never apply a sandbox directly inside a global test runner:
* In C: Test sandboxes inside a fork() block, checking the child's exit status with waitpid().
* In Lua: Execute test scenarios via os.execute("lua -e '...'") in an isolated subprocess.
3. LuaJIT and Dynamic Code Hardening¶
The dynamic_code = false setting prohibits memory pages with Write+Execute (PAGE_EXECUTE_READWRITE).
* If running on LuaJIT, disabling dynamic code will prevent the JIT compiler from allocating machine code stubs. Either disable the JIT first (jit.off()) or keep dynamic_code = true.
* Standard PUC Lua (5.4 and 5.5) uses a pure bytecode interpreter on the C stack and is 100% compatible with dynamic_code = false.
4. Path Canonicalization¶
When passing paths to allow(), prefer canonical absolute paths or consistent relative paths. If a declared path does not exist on disk at the moment apply() is invoked, kernel backends like Landlock and Seatbelt will reject the rule with an ENOENT error.
🔍 8. Troubleshooting & Diagnostics¶
| Symptom | Probable Cause | Recommended Resolution |
|---|---|---|
apply() fails with "No such file or directory" |
A path passed to allow_path does not exist on disk at apply time. |
Verify path existence with cais.fs.exists() before calling apply(). |
apply() returns CAIS_SANDBOX_UNSUPPORTED (-4) |
Host OS is older than minimum kernel version or sandbox is uncompiled. | Treat -4 as a non-fatal warning on vintage platforms if full security is optional. |
Subsequent require("foo") fails with "permission denied" |
Module was required after the sandbox restricted the filesystem. | Move all require() statements to the top of the entry point prior to apply(). |
| Process crashes immediately on Windows | Invalid handle passed with Strict Handle Check active. | Ensure all file/socket handles are properly checked before closing. |