Relevant source files

The following files were used as context for generating this wiki page: - [internal/sandbox/linux.go](https://github.com/Use-Tusk/fence/blob/main/internal/sandbox/linux.go) - [ARCHITECTURE.md](https://github.com/Use-Tusk/fence/blob/main/ARCHITECTURE.md) - [internal/sandbox/integration_linux_test.go](https://github.com/Use-Tusk/fence/blob/main/internal/sandbox/integration_linux_test.go) - [internal/sandbox/linux_landlock_stub.go](https://github.com/Use-Tusk/fence/blob/main/internal/sandbox/linux_landlock_stub.go) - [README.md](https://github.com/Use-Tusk/fence/blob/main/README.md)

# Linux Security Technologies Fence utilizes a multi-layered security approach on Linux to restrict network, filesystem, and command access. The project leverages native Linux kernel features to provide isolation and enforcement for semi-trusted code execution, build scripts, and CI jobs. The Linux implementation relies on four primary security layers: isolation via Linux namespaces (Bubblewrap), syscall filtering (Seccomp), filesystem access control (Landlock), and violation visibility (eBPF). These technologies work in concert with a graceful fallback mechanism to ensure the highest possible level of security based on the host kernel's capabilities. Sources: [ARCHITECTURE.md:7-11](), [ARCHITECTURE.md:214-220](), [README.md:14-17]() ## Core Isolation: Bubblewrap (bwrap) The foundation of the Linux sandbox is `bubblewrap` (bwrap), which utilizes Linux namespaces to create an isolated execution environment. By default, Fence uses bwrap to unshare network and PID namespaces, preventing the sandboxed process from seeing other host processes or accessing the host network directly. ### Network Isolation and Socat Bridging Because the sandbox has its own network namespace (`--unshare-net`), it cannot reach the host's network. Fence overcomes this by using Unix sockets and `socat` to bridge traffic between the sandbox and the host's filtering proxies. ```mermaid flowchart TD subgraph Host HTTP_Proxy[HTTP Proxy] SOCKS_Proxy[SOCKS Proxy] HSocat_HTTP[Host socat HTTP] HSocat_SOCKS[Host socat SOCKS] USock_HTTP((Unix Socket HTTP)) USock_SOCKS((Unix Socket SOCKS)) end subgraph Sandbox["Sandbox (bwrap --unshare-net)"] Cmd[User Command] ISocat_HTTP[Sandbox socat HTTP] ISocat_SOCKS[Sandbox socat SOCKS] end HTTP_Proxy <--> HSocat_HTTP <--> USock_HTTP SOCKS_Proxy <--> HSocat_SOCKS <--> USock_SOCKS USock_HTTP <-->|Bind Mounted| ISocat_HTTP USock_SOCKS <-->|Bind Mounted| ISocat_SOCKS Cmd -.->|HTTP_PROXY| ISocat_HTTP Cmd -.->|ALL_PROXY| ISocat_SOCKS ``` The diagram shows how Unix sockets provide filesystem-based IPC that traverses namespace boundaries to allow filtered network access. Sources: [ARCHITECTURE.md:140-165](), [internal/sandbox/linux.go:42-108]() ### Filesystem Sandboxing Bubblewrap manages the initial filesystem view through mount flags. Fence typically binds the entire root filesystem as read-only (`--ro-bind / /`) and then selectively overlays writable paths or masks sensitive areas. | bwrap Flag | Description | | :--- | :--- | | `--ro-bind` | Mounts a path as read-only (default for `/`). | | `--bind` | Mounts a path as writable (used for `allowWrite` paths). | | `--tmpfs` | Mounts an empty, ephemeral filesystem (used for `/tmp` and `denyRead` masking). | | `--dev-bind` | Binds `/dev` to preserve host device permissions. | | `--proc` | Mounts a new `/proc` filesystem for the PID namespace. | Sources: [internal/sandbox/linux.go:400-500](), [ARCHITECTURE.md:155-160]() ## Filesystem Control: Landlock Landlock provides fine-grained filesystem access control at the kernel level, introduced in Linux 5.13. Fence uses Landlock to enforce read/write restrictions that are more robust than simple mount flags, especially for handling glob patterns and protecting specific files within a directory. ### Landlock Enforcement Logic Fence applies Landlock rules through a wrapper mode (`--landlock-apply`). This mode re-executes the command with Landlock rulesets applied to the process tree. * **Rule Application**: Landlock rules are applied to specific paths to allow or deny `READ`, `WRITE`, `REFER`, and `MAKE` operations. * **Default Protection**: Fence automatically protects mandatory paths such as `.bashrc`, `.zshrc`, `.git/hooks`, and `.git/config` via Landlock to prevent injection attacks. * **Graceful Fallback**: If the kernel does not support Landlock (ABI < 1), Fence falls back to standard Bubblewrap mount-based restrictions. Sources: [internal/sandbox/linux.go:580-600](), [internal/sandbox/integration_linux_test.go:21-36](), [ARCHITECTURE.md:217-219]() ## Syscall Filtering: Seccomp BPF Fence uses Seccomp (Secure Computing) with BPF (Berkeley Packet Filter) to restrict the system calls available to the sandboxed process. This reduces the kernel attack surface by blocking dangerous or unnecessary syscalls. ### Dangerous Syscall Blocking The Seccomp filter is generated as a BPF program and applied via an open file descriptor (typically fd 3) during Bubblewrap initialization. ```mermaid flowchart TD Init[Initialize Seccomp Filter] --> Gen[Generate BPF Filter] Gen --> File[Write to Temporary File] File --> FD[Open File as FD 3] FD --> Bwrap[Execute bwrap --seccomp 3] Bwrap --> Exec[Run User Command] ``` The Seccomp implementation silently blocks syscalls by returning `SECCOMP_RET_ERRNO` (EPERM), which prevents logs from appearing in `dmesg` or audit logs to reduce noise. Sources: [internal/sandbox/linux.go:384-400](), [internal/sandbox/linux.go:670-685](), [ARCHITECTURE.md:214-220]() ## Violation Monitoring: eBPF To provide visibility into blocked operations, Fence includes an eBPF-based monitor. This is particularly useful when Seccomp or Landlock blocks an operation silently. * **Functionality**: The eBPF monitor traces syscall exits that return `EPERM` or `EACCES` for processes within the sandbox's PID tree. * **Requirements**: Requires `root` privileges or `CAP_BPF` to load the eBPF programs. * **Monitor Mode**: Enabled via the `-m` flag, it outputs violations prefixed with `[fence:ebpf]`. Sources: [internal/sandbox/linux.go:690-710](), [ARCHITECTURE.md:237-240]() ## Feature Detection and Compatibility Fence includes a detection system to determine which security technologies are available on the host system. This allows the sandbox to adapt its security posture based on the environment (e.g., standard OS vs. containerized CI). ```go func PrintLinuxFeatures() { features := DetectLinuxFeatures() fmt.Printf("Linux Sandbox Features:\n") fmt.Printf(" Bubblewrap (bwrap): %v\n", features.HasBwrap) fmt.Printf(" Seccomp: %v\n", features.HasSeccomp) fmt.Printf(" Landlock: %v (ABI v%d)\n", features.HasLandlock, features.LandlockABI) fmt.Printf(" eBPF: %v\n", features.HasEBPF) } ``` Sources: [internal/sandbox/linux.go:722-770]() The multi-layered approach ensures that even if one technology is unavailable (e.g., Landlock on older kernels), the others (Bubblewrap, Seccomp) still provide significant protection. The combination of network namespace isolation and local `socat` bridges allows for strict domain-based filtering while maintaining compatibility with standard tools like `curl`, `git`, and `npm`. Sources: [ARCHITECTURE.md:214-225](), [README.md:14-17]()