Process Sandbox

Constrained Process Execution Layer

A foundational library providing robust process isolation and sandboxing mechanisms for running untrusted or sensitive code in controlled environments.

Overview

process-sandbox provides fine-grained control over process execution boundaries, resource limits, and syscall filtering. It enables secure execution of potentially malicious or buggy code by constraining what operations a process can perform.

Features

Core Capabilities

• Process Isolation: Create isolated process environments using Linux namespaces
• Resource Constraints: CPU, memory, file descriptor, and process limits
• Filesystem Isolation: Chroot jails and mount namespace management
• Network Isolation: Network namespace control for network-less execution
• IPC Isolation: Inter-process communication restrictions
• UID/GID Mapping: User namespace support for unprivileged containers

Advanced Features

• Nested Sandboxes: Support for multi-layer isolation
• Dynamic Policy Updates: Modify sandbox constraints at runtime
• Execution Monitoring: Hook points for observing sandboxed processes
• Resource Accounting: Track resource usage of sandboxed processes
• Clean Teardown: Reliable cleanup of sandbox resources

Architecture

┌─────────────────────────────────────────────┐
│         Application Layer                   │
│  (Your code using process-sandbox)          │
└─────────────────┬───────────────────────────┘
                  │
┌─────────────────▼───────────────────────────┐
│     Process Sandbox API                     │
│  - SandboxBuilder                           │
│  - SandboxConfig                            │
│  - SandboxExecutor                          │
└─────────────────┬───────────────────────────┘
                  │
┌─────────────────▼───────────────────────────┐
│     Isolation Primitives                    │
│  - Namespace Manager                        │
│  - Resource Limiter                         │
│  - Capability Controller                    │
└─────────────────┬───────────────────────────┘
                  │
┌─────────────────▼───────────────────────────┐
│      Linux Kernel Interfaces                │
│  - namespaces, cgroups, rlimits, prctl      │
└─────────────────────────────────────────────┘

Installation

As a Git Submodule

git submodule add https://github.com/navinBRuas/_SecureExecutionEnvironment.git vendor/secure-execution
cd vendor/secure-execution/process-sandbox
make

As a System Library

make install PREFIX=/usr/local

Quick Start

Basic Example (C)

#include <process-sandbox/sandbox.h>

int main() {
    // Create sandbox configuration
    sandbox_config_t config = sandbox_config_new();
    
    // Configure isolation
    sandbox_config_set_namespaces(&config, 
        SANDBOX_NS_PID | SANDBOX_NS_NET | SANDBOX_NS_MOUNT);
    
    // Set resource limits
    sandbox_config_set_memory_limit(&config, 100 * 1024 * 1024); // 100 MB
    sandbox_config_set_cpu_shares(&config, 512);
    
    // Execute sandboxed process
    const char *argv[] = {"/bin/ls", "-la", NULL};
    int result = sandbox_exec(&config, "/bin/ls", argv);
    
    // Clean up
    sandbox_config_destroy(&config);
    
    return result;
}

Python Bindings

from process_sandbox import Sandbox, NamespaceFlags, ResourceLimits

# Create sandbox with configuration
sandbox = Sandbox()
sandbox.set_namespaces(NamespaceFlags.PID | NamespaceFlags.NET)
sandbox.set_memory_limit(100 * 1024 * 1024)  # 100 MB
sandbox.set_cpu_shares(512)

# Execute command
result = sandbox.exec(['/bin/ls', '-la'])
print(f"Exit code: {result.exit_code}")

API Reference

Sandbox Configuration

sandbox_config_new()

Creates a new sandbox configuration with default settings.

sandbox_config_set_namespaces(config, flags)

Configure which Linux namespaces to use:

• SANDBOX_NS_PID - Process ID namespace
• SANDBOX_NS_NET - Network namespace
• SANDBOX_NS_MOUNT - Mount namespace
• SANDBOX_NS_UTS - Hostname namespace
• SANDBOX_NS_IPC - Inter-process communication namespace
• SANDBOX_NS_USER - User namespace

sandbox_config_set_memory_limit(config, bytes)

Set maximum memory usage in bytes.

sandbox_config_set_cpu_shares(config, shares)

Set relative CPU scheduling priority (100-1024).

sandbox_config_set_rootfs(config, path)

Set the root filesystem for the sandbox.

Execution

sandbox_exec(config, path, argv)

Execute a program in the configured sandbox.

sandbox_spawn(config, path, argv, callback)

Spawn a sandboxed process with a callback for monitoring.

Monitoring

sandbox_get_stats(pid, stats)

Retrieve resource usage statistics for a sandboxed process.

Configuration Examples

Maximum Security

sandbox_config_t config = sandbox_config_new();

// Full isolation
sandbox_config_set_namespaces(&config, 
    SANDBOX_NS_PID | SANDBOX_NS_NET | SANDBOX_NS_MOUNT | 
    SANDBOX_NS_UTS | SANDBOX_NS_IPC | SANDBOX_NS_USER);

// Strict resource limits
sandbox_config_set_memory_limit(&config, 50 * 1024 * 1024);
sandbox_config_set_cpu_shares(&config, 256);
sandbox_config_set_max_fds(&config, 10);
sandbox_config_set_max_processes(&config, 1);

// Read-only root filesystem
sandbox_config_set_rootfs(&config, "/tmp/sandbox-root");
sandbox_config_set_readonly_root(&config, true);

// No network access
sandbox_config_set_network_enabled(&config, false);

Development/Testing

sandbox_config_t config = sandbox_config_new();

// Light isolation for debugging
sandbox_config_set_namespaces(&config, SANDBOX_NS_PID);

// Generous limits
sandbox_config_set_memory_limit(&config, 1024 * 1024 * 1024); // 1 GB
sandbox_config_set_cpu_shares(&config, 1024);

// Keep network access
sandbox_config_set_network_enabled(&config, true);

Integration with Other Projects

With seccomp-profiles

#include <process-sandbox/sandbox.h>
#include <seccomp-profiles/profile.h>

sandbox_config_t config = sandbox_config_new();
seccomp_profile_t *profile = seccomp_profile_load("strict.json");

sandbox_config_set_seccomp_profile(&config, profile);
sandbox_exec(&config, "/bin/untrusted", argv);

With capability-based-security

#include <process-sandbox/sandbox.h>
#include <capability-based-security/caps.h>

sandbox_config_t config = sandbox_config_new();
cap_set_t caps = cap_set_new();

cap_set_add(&caps, CAP_NET_BIND_SERVICE);
sandbox_config_set_capabilities(&config, &caps);

Building

Requirements

• Linux kernel 5.0+ (for full namespace support)
• GCC 9+ or Clang 10+
• make
• libcap-dev (for capability support)

Build Commands

# Debug build
make DEBUG=1

# Release build
make

# With tests
make test

# Install
sudo make install

Testing

# Run unit tests
make test-unit

# Run integration tests
make test-integration

# Run all tests
make test

# With coverage
make coverage

Performance Considerations

• Namespace creation: ~1-2ms overhead per sandbox creation
• Memory overhead: ~10MB per sandbox (for namespace metadata)
• CPU overhead: <1% for monitoring and enforcement
• Recommended: Pre-fork sandbox pool for high-frequency usage

Security Notes

• Always use the most restrictive configuration for your use case
• Combine with seccomp-bpf for syscall filtering
• Use capability dropping to enforce least privilege
• Monitor sandbox violations in production
• Keep kernel updated for security patches

Troubleshooting

"Permission denied" when creating namespaces

Ensure you have CAP_SYS_ADMIN or are running as root. For unprivileged containers, use user namespaces.

Sandbox process can access parent filesystem

Check mount namespace configuration and ensure proper chroot/pivot_root usage.

Resource limits not enforced

Verify cgroup v2 is enabled: grep cgroup2 /proc/mounts

Contributing

See CONTRIBUTING.md for development guidelines.

License

MIT License - See LICENSE

Changelog

See CHANGELOG.md for version history.

References

• Linux Namespaces
• Control Groups
• Resource Limits

Standalone Installation

git submodule add https://github.com/navinBRuas/_SecureExecutionEnvironment.git vendor/secure-execution

Use vendor/secure-execution/process-sandbox for local builds and integration.

Usage

Follow the C and Python examples above and module headers for full API details.

Configuration

Configure namespaces, limits, filesystem, and seccomp profiles via sandbox_config_t or the Python Sandbox API.

Version

Current version: 0.1.0 (see VERSION.md).

Changelog

See CHANGELOG.md for release history.