sandworm

A network proxy for container-based sandbox environments.

Overview

sandworm is a standalone HTTP/HTTPS proxy server designed to run in containerized environments. It provides configurable domain and CIDR filtering to control network access from sandboxed containers.

IP Mode

sandworm supports an advanced "IP Mode" that allows mapping specific domains to IP addresses within a configurable CIDR range. This enables clients to connect directly to these IPs, which sandworm then proxies to the corresponding domains.

Current Implementation:

• TCP works
• UDP, ICMP, and friends are on a roadmap

Usage:

sandworm --port 2137 \
  --domains "api.example.com,db.internal.com" \
  --ip-proxy-range "192.168.100.0/24" \
  --ip-ports "80,443,5432" \
  --dns-port 53

This will:

• Map each specific domain to an IP in the 192.168.100.0/24 range
• Listen on ports 80, 443, and 5432 for direct IP connections
• Run a DNS server on port 53 to resolve mapped domains to their assigned IPs
• Proxy these connections to the corresponding domains

Clients can then configure their DNS (e.g., /etc/hosts) to point domains to the assigned IPs and connect directly.

Getting /etc/hosts entries:

sandworm etchosts --domains "api.example.com,db.internal.com" --ip-proxy-range "192.168.100.0/24"

This outputs copy-pastable /etc/hosts entries showing the deterministic IP mappings.

Usage

sandworm --port 2137 --domains "github.com,golang.org" --cidrs "10.0.0.0/8"

Options

• --port, -p: Proxy port (default: 2137)
• --admin, -a: Enable admin panel (default: false)
• --domains, -d: Comma-separated list of allowed domains
• --cidrs, -c: Comma-separated list of allowed CIDRs
• --log-level, -l: Log level (debug, info, warn, error) (default: info)
• --ip-proxy-range: CIDR range for IP mode domain mapping
• --ip-ports: Comma-separated list of ports for IP mode
• --dns-port: DNS server port (requires IP mode)

Building

go build -o sandworm ./cmd/sandworm

Docker

Build the Docker image with the accompanying Dockerfile. For size-optimized builds, there's also a script:

./build-minimal-image.sh

Official image

Go ahead and grab one, it's just 12MB at the time of writing! https://hub.docker.com/r/poolsideengineering/sandworm

docker pull poolsideengineering/sandworm:latest

Low quality ASCII art architecture layout

                 ┌─────────┐
                 │  cont2  │
┌─────────┐      └─────┬───┘     ┌─────────┐
│  cont1  │──────┐     │    ┌────┼  cont3  │
└─────────┘      │     │    │    └─────────┘
                 │     │    │
             ┌───▼─────▼────▼──┐
             │ internal network│
             │  172.31.0.0/24  │
             └────────┬────────┘
                      │
             ┌────────▼─────────┐
             │     sandworm     │
             │                  │◄─┐
             └────────┬─────────┘  │
                      │            │
             ┌────────▼─────────┐  │
             │ isolated network │──┘
             │  172.32.0.0/24   │
             └────────┬─────────┘
                      │
                      ▼
                  xxxxxxxxxxx
               xxx       xxxxxxx
              x             xxxxx
             x                 xx
             x  world wide web   x
             x ~~~~             xx
             x~~~~~~~          xxx
             x~~~~~~~          xx
               xx~~~~~~~~~  xxx
                   xxxxxxxxx

Low quality screenshot of the admin panel

Yes, we have one!