arapuca

README

go-arapuca

Go bindings for arapuca, a Linux/macOS process sandbox. Wraps the C API via cgo to provide idiomatic Go types for launching sandboxed subprocesses.

What arapuca enforces

On Linux: Landlock filesystem restrictions, seccomp BPF syscall filtering, cgroups v2 resource limits (memory, CPU, PIDs), network namespace isolation, rlimits, pdeathsig, setsid, environment sanitization.

On macOS: Apple's sandbox-exec (Seatbelt) with deny-default profiles, rlimits, memory polling, parent-PID watchdog.

Prerequisites

• Go 1.25+ with CGO_ENABLED=1
• C compiler (gcc or clang)
• pkg-config
• libarapuca.a, arapuca.h, and arapuca.pc installed where pkg-config can find them (see Building the C library)

Install

go get github.com/sergio-correia/go-arapuca

Versioning

go-arapuca links against arapuca's C ABI via pkg-config. There is no automatic version coupling — you must keep them in sync. Each go-arapuca release documents the minimum arapuca version it requires:

go-arapuca	arapuca (min)
v0.2.0+	v0.1.1
v0.1.x	v0.1.0

If you see link errors or crashes, rebuild and reinstall the C library first.

Usage

Process-level sandbox

package main

import (
    "context"
    "fmt"
    "log"

    arapuca "github.com/sergio-correia/go-arapuca"
)

func main() {
    sb, err := arapuca.New()
    if err != nil {
        log.Fatal(err)
    }
    defer sb.Close()

    cfg := arapuca.Config{
        Profile: arapuca.Profile{
            ReadPaths:   []string{"/usr", "/lib", "/lib64", "/bin", "/etc", "/dev"},
            WritePaths:  []string{"/tmp/workspace"},
            MaxMemoryMB: 2048,
            MaxPIDs:     256,
            MaxCPUPct:   200, // 2 cores
            UseNetNS:    true,
        },
        TaskID:  "task-42",
        Phase:   "execute",
        WorkDir: "/tmp/workspace",
    }

    proc, err := sb.Launch(context.Background(), cfg, "/usr/bin/python3", []string{"agent.py"}, nil)
    if err != nil {
        log.Fatal(err)
    }

    exitCode, err := proc.Wait()
    if err != nil {
        log.Printf("process error: %v", err)
    }

    stats := proc.ResourceStats()
    fmt.Printf("exit=%d peak_memory=%d bytes\n", exitCode, stats.MemoryPeakBytes)

    proc.Cleanup()
}

Micro-VM isolation (Linux only, requires -tags microvm)

package main

import (
    "context"
    "fmt"
    "log"

    arapuca "github.com/sergio-correia/go-arapuca"
)

func main() {
    if !arapuca.MicroVmAvailable() {
        log.Fatal("micro-VM isolation not available (no KVM?)")
    }

    // Pull image (~500MB first time, cached for reuse).
    imagePath, err := arapuca.ImagePull("fedora", "42")
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println("image:", imagePath)

    sb, err := arapuca.New()
    if err != nil {
        log.Fatal(err)
    }
    defer sb.Close()

    cfg := arapuca.Config{
        Profile: arapuca.Profile{
            ReadPaths:  []string{"/home/user/project"},
            WritePaths: []string{"/tmp/workspace"},
            Isolation: &arapuca.MicroVmIsolation{
                Distro:  "fedora",
                Version: "42",
                CPUs:    2,
                MemMB:   2048,
            },
        },
        TaskID: "vm-task-1",
        Phase:  "execute",
    }

    proc, err := sb.Launch(context.Background(), cfg, "make", []string{"test"}, nil)
    if err != nil {
        log.Fatal(err)
    }

    exitCode, _ := proc.Wait()
    fmt.Printf("exit=%d\n", exitCode)
    proc.Cleanup()
}

API

Sandbox

arapuca.New() (*Sandbox, error)           // create sandbox handle
sb.Launch(ctx, cfg, cmd, args, extraFiles)  // launch sandboxed subprocess
sb.CgroupsAvailable() bool                 // probe cgroups v2
sb.Close()                                 // release handle

Process

proc.PID() int                     // subprocess PID
proc.Wait() (int, error)           // wait for exit (code, error)
proc.ResourceStats() ResourceUsage // cgroup stats (before Cleanup)
proc.OOMCount() int                // OOM kill count (before Cleanup)
proc.Cleanup()                     // release resources

Micro-VM (requires -tags microvm)

arapuca.MicroVmAvailable() bool                  // probe KVM + qemu-img
arapuca.ImagePull(distro, version) (string, error) // download and cache image

Without the build tag, MicroVmAvailable() returns false and ImagePull() returns an error.

Utilities

arapuca.MakeSocketDir() (string, error)  // temp dir for Unix sockets
arapuca.MakeTmpDir(taskID) (string, error)
arapuca.WrapperPath() string             // find arapuca binary
arapuca.LandlockABIVersion() int         // 0 if unavailable
arapuca.NetNSAvailable() bool
arapuca.DiskUsageMB(path) uint64

Types

type Profile struct {
    ReadPaths, WritePaths []string
    MaxMemoryMB           uint64             // 0 = no limit
    MaxCPUPct             uint32             // 0 = no limit; 200 = 2 cores
    MaxPIDs               uint32
    MaxFileSizeMB         uint64
    UseNetNS              bool
    Isolation             *MicroVmIsolation  // nil = process-level sandbox
}

type MicroVmIsolation struct {
    Distro    string  // e.g. "fedora", "centos" (or use ImagePath)
    Version   string  // e.g. "42", "9"
    ImagePath string  // explicit qcow2 path (alternative to Distro/Version)
    CPUs      uint32
    MemMB     uint32
}

type Config struct {
    Profile            Profile
    SocketDir          string
    TaskID             string
    Phase              string
    WorkDir            string
    Stdin              *os.File          // nil = inherit
    Stdout, Stderr     *os.File          // nil = inherit
    NetworkProxySocket string
    Env                map[string]string // extra env vars for subprocess
}

type ResourceUsage struct {
    MemoryCurrentBytes, MemoryPeakBytes int64
    CPUUsageSeconds                     float64
    PIDCount                            int64
    IOReadBytes, IOWriteBytes           int64
}

Thread Safety

• Sandbox is safe for concurrent use (mutex-protected).
• Process methods are safe for concurrent use (mutex-protected).
• Error checking uses runtime.LockOSThread() to pin goroutines to OS threads (arapuca uses thread-local error storage).
• Context cancellation sends SIGKILL to the process group.

Building the C library

go-arapuca links against libarapuca.a (a Rust static library) discovered via pkg-config. Two build modes are available:

Core sandbox (all platforms)

make setup

Installs process-level sandbox support only. No libkrun or OpenSSL development packages required.

With micro-VM support (Linux only)

make setup-microvm

Installs with micro-VM isolation via libkrun. Requires libkrun-devel and openssl-devel (or equivalent) packages. Build Go code with -tags microvm:

go build -tags microvm ./...

Build matrix

arapuca install	go-arapuca build	Result
make setup	go build	core sandbox only
make setup	go build -tags microvm	link error
make setup-microvm	go build	core sandbox only
make setup-microvm	go build -tags microvm	full micro-VM support

Custom paths

# Custom arapuca checkout and install prefix
make setup ARAPUCA_DIR=/path/to/arapuca PREFIX=/opt/arapuca

# Ensure pkg-config finds the installed library
export PKG_CONFIG_PATH=$HOME/.local/lib/pkgconfig

Re-run make setup (or make setup-microvm) whenever the arapuca library changes.

License

Apache-2.0

Documentation

Overview

Package arapuca provides Go bindings for the arapuca process sandbox library via cgo. It wraps the C API to provide idiomatic Go types for sandboxed subprocess management.

Arapuca enforces OS-level isolation (Landlock, seccomp BPF, cgroups v2, network namespaces on Linux; sandbox-exec on macOS) on untrusted subprocesses.

Thread safety: arapuca_last_error() uses thread-local storage. All cgo call sequences that check errors use runtime.LockOSThread() to prevent Go's goroutine scheduler from moving the goroutine to a different OS thread between the call and the error check.

Index

• func DiskUsageMB(path string) uint64
• func ImagePull(_, _ string) (string, error)
• func LandlockABIVersion() int
• func MakeSocketDir() (string, error)
• func MakeTmpDir(taskID string) (string, error)
• func MicroVmAvailable() bool
• func NetNSAvailable() bool
• func WrapperPath() string
• type Config
• type MicroVmIsolation
• type Process
  • func (p *Process) Cleanup()
  • func (p *Process) OOMCount() int
  • func (p *Process) PID() int
  • func (p *Process) ResourceStats() ResourceUsage
  • func (p *Process) Wait() (int, error)
• type Profile
• type ResourceUsage
• type Sandbox
  • func New() (*Sandbox, error)
  • func (s *Sandbox) CgroupsAvailable() bool
  • func (s *Sandbox) Close()
  • func (s *Sandbox) Launch(ctx context.Context, cfg Config, cmd string, args []string, ...) (*Process, error)

Functions

func DiskUsageMB

func DiskUsageMB(path string) uint64

DiskUsageMB returns the disk usage of a directory in MB.

func ImagePull

func ImagePull(_, _ string) (string, error)

ImagePull is unavailable without the microvm build tag.

func LandlockABIVersion

func LandlockABIVersion() int

LandlockABIVersion probes the kernel's Landlock ABI version. Returns 0 if Landlock is unavailable.

func MakeSocketDir

func MakeSocketDir() (string, error)

MakeSocketDir creates a temporary directory with mode 0700 and a random suffix for per-agent Unix sockets. The caller is responsible for removing the directory when done.

func MakeTmpDir

func MakeTmpDir(taskID string) (string, error)

MakeTmpDir creates a temporary directory for the given task with a random suffix. The caller is responsible for removing it.

func MicroVmAvailable

func MicroVmAvailable() bool

MicroVmAvailable always returns false without the microvm build tag.

func NetNSAvailable

func NetNSAvailable() bool

NetNSAvailable probes whether network namespace isolation works.

func WrapperPath

func WrapperPath() string

WrapperPath returns the path to the arapuca binary, or empty string if not found.

Types

type Config

type Config struct {
	Profile            Profile
	SocketDir          string            // Per-agent socket directory.
	TaskID             string            // Task identifier.
	Phase              string            // Current phase (opaque to arapuca).
	WorkDir            string            // Working directory (empty = inherit).
	Stdin              *os.File          // Redirect stdin (nil = inherit).
	Stdout             *os.File          // Redirect stdout (nil = inherit).
	Stderr             *os.File          // Redirect stderr (nil = inherit).
	NetworkProxySocket string            // Path to network proxy Unix socket.
	Env                map[string]string // Caller-supplied env vars for subprocess.
}

Config holds the full configuration for launching a sandboxed process.

type MicroVmIsolation

type MicroVmIsolation struct {
	Distro    string // Distro name (e.g. "fedora", "centos"). Mutually exclusive with ImagePath.
	Version   string // Distro version (e.g. "42", "9"). Mutually exclusive with ImagePath.
	ImagePath string // Explicit qcow2 path. Mutually exclusive with Distro/Version.
	CPUs      uint32 // Number of vCPUs (must be > 0).
	MemMB     uint32 // Memory in MB (must be > 0).
}

MicroVmIsolation configures micro-VM isolation via libkrun. Set either Distro+Version or ImagePath, not both. Requires building with -tags microvm against a microvm-enabled libarapuca.a (make install INSTALL_FEATURES=microvm).

type Process

type Process struct {
	// contains filtered or unexported fields
}

Process represents a running sandboxed subprocess.

func (*Process) Cleanup

func (p *Process) Cleanup()

Cleanup releases the subprocess's resources (temp directory, cgroup). Must only be called after Wait() returns. Safe to call multiple times.

func (*Process) OOMCount

func (p *Process) OOMCount() int

OOMCount reads the OOM kill count from the subprocess's cgroup. Must be called before Cleanup().

func (*Process) PID

func (p *Process) PID() int

PID returns the process ID of the sandboxed subprocess.

func (*Process) ResourceStats

func (p *Process) ResourceStats() ResourceUsage

ResourceStats reads resource usage from the subprocess's cgroup. Must be called before Cleanup(). Returns zero values if cgroups are unavailable.

func (*Process) Wait

func (p *Process) Wait() (int, error)

Wait waits for the subprocess to exit. Returns the exit code and any error. If the process was killed by a signal, the exit code is 0 and the error describes the signal.

type Profile

type Profile struct {
	ReadPaths     []string          // Allowed read-only paths.
	WritePaths    []string          // Allowed read-write paths.
	MaxMemoryMB   uint64            // Memory limit in MB (0 = no limit).
	MaxCPUPct     uint32            // CPU percentage (0 = no limit; 200 = 2 cores).
	MaxPIDs       uint32            // Max processes (0 = no limit).
	MaxFileSizeMB uint64            // Max file size in MB (0 = no limit).
	UseNetNS      bool              // Use network namespace isolation.
	Isolation     *MicroVmIsolation // Micro-VM isolation (nil = process-level sandbox).
}

Profile defines the restrictions applied to a sandboxed subprocess.

type ResourceUsage

type ResourceUsage struct {
	MemoryCurrentBytes int64
	MemoryPeakBytes    int64
	CPUUsageSeconds    float64
	PIDCount           int64
	IOReadBytes        int64
	IOWriteBytes       int64
}

ResourceUsage holds cgroup v2 resource usage statistics.

type Sandbox

type Sandbox struct {
	// contains filtered or unexported fields
}

Sandbox wraps the arapuca sandbox handle. It is the entry point for launching sandboxed subprocesses. Create with New().

func New

func New() (*Sandbox, error)

New creates a new sandbox for the current platform.

func (*Sandbox) CgroupsAvailable

func (s *Sandbox) CgroupsAvailable() bool

CgroupsAvailable reports whether cgroups v2 resource limits are available on this system.

func (*Sandbox) Close

func (s *Sandbox) Close()

Close releases the sandbox handle. Safe to call multiple times.

func (*Sandbox) Launch

func (s *Sandbox) Launch(ctx context.Context, cfg Config, cmd string, args []string, extraFiles []*os.File) (*Process, error)

Launch starts a sandboxed subprocess. The subprocess is isolated according to the Config's Profile. Extra file descriptors in extraFiles are inherited by the subprocess at FD positions 3, 4, ...

The returned Process must be waited on and cleaned up.

Context cancellation: if ctx is cancelled, the subprocess is killed via SIGKILL to the process group.