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.

Filtering Modes

sandworm supports two mutually exclusive filtering modes:

• Allow mode (default): only destinations on the allow list (--domains, --cidrs) are reachable. Everything else is blocked.
• Block mode: everything is reachable except destinations on the block list (--blocked-domains, --blocked-cidrs).

Block mode is not compatible with IP mode (see below). Passing --mode block together with --ip-proxy-range is an error.

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

Allow mode (default) — only the listed domains/CIDRs are reachable:

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

Block mode — everything is reachable except the listed domains/CIDRs:

sandworm --port 2137 --mode block --blocked-domains "facebook.com,*.ads.example.com"

Note: block mode cannot be used together with --ip-proxy-range.

Options

• --port, -p: Proxy port (default: 2137)
• --admin, -a: Enable admin panel (deprecated; binds to 127.0.0.1)
• --admin-bind: Admin panel bind address (empty disables)
• --mode: Filtering mode: allow (whitelist) or block (blacklist) (default: allow)
• --domains, -d: Comma-separated list of allowed domains (allow mode)
• --cidrs, -c: Comma-separated list of allowed CIDRs (allow mode)
• --blocked-domains: Comma-separated list of blocked domains (block mode)
• --blocked-cidrs: Comma-separated list of blocked CIDRs (block mode)
• --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!