crackbox · reference

commands, config, behavior, integration · ← crackbox

commands

crackbox proxy serve [--config <path>] [--listen :3128] [--admin :3129] [--transparent :3127]
crackbox run --allow <list> [--id <name>] [--image <img>] -- <cmd>...
crackbox state [--admin <url>]

proxy serve — long-lived daemon. Lifecycle owned by Docker compose or systemd; no idle-shutdown, no auto-restart inside the binary.
run — one-shot wrapper. Creates a private Docker network, starts the daemon on it, registers one entry, runs the workload with HTTPS_PROXY set, tears everything down on exit.
state — query a running daemon’s registry.

configuration file

Optional TOML, looked up in order: --config path, $XDG_CONFIG_HOME/crackbox/crackbox.toml, ~/.crackboxrc, /etc/crackbox.toml. Missing file is fine. Precedence: flags > env > config > defaults.

[proxy]
listen = ":3128"
admin_listen = ":3129"
transparent_listen = ":3127"   # set to "" to disable

[admin]
secret = ""                    # bearer token; empty disables auth

[state]
path = ""                      # registry persistence; empty = RAM-only

environment variables

var	default	used by
`CRACKBOX_PROXY_ADDR`	`:3128`	forward proxy listener
`CRACKBOX_ADMIN_ADDR`	`:3129`	admin API listener
`CRACKBOX_TRANSPARENT_ADDR`	`:3127`	transparent listener; empty disables
`CRACKBOX_ADMIN_SECRET`	(unset)	bearer token for mutating endpoints
`CRACKBOX_STATE_PATH`	(unset)	JSON file for registry persistence
`CRACKBOX_IMAGE`	`crackbox:latest`	`crackbox run` proxy image
`CRACKBOX_SUBNET`	`10.88.0.0/16`	`crackbox run` Docker subnet
`CRACKBOX_ADMIN`	`http://localhost:3129`	`crackbox state` target

persistence

CRACKBOX_STATE_PATH empty keeps the registry RAM-only; restarts drop state. When set, every register / unregister rewrites the file atomically (tmp + rename) and startup reloads it. Corrupt or missing files reset to empty with a warning — a stale snapshot can never block startup.

uninstall

docker rmi crackbox:latest
docker network ls | grep crackbox- | awk '{print $1}' | xargs -n1 docker network rm

matching

The registry is source-IP → (id, allowlist). One pure matchHost function decides every connection. Host name only: exact, subdomain-aware, case-insensitive, trailing dot stripped. No IP rules, no path rules, no per-method rules. Transparent mode is restricted to ports 80 and 443; forward-mode CONNECT passes any port the destination accepts.

how traffic arrives

Forward. Workload sets HTTPS_PROXY=http://crackbox:3128. crackbox accepts HTTP forward requests and CONNECT tunnels for HTTPS, reads the destination from the request line, splices on success.

Transparent. Client side runs iptables ... REDIRECT --to-ports 3127 on outbound :80/:443. crackbox reads the pre-NAT destination via SO_ORIGINAL_DST, peeks the SNI (443) or Host: (80), splices. Linux only.

Both share the same registry and the same allowlist check. Bind both, neither, or one — whatever fits the topology.

what it doesn’t do

no TLS interception or MITM
no secret injection into outbound requests
no response scanning or content filtering
no traffic auditing or per-request logs
no runtime allowlist mutation outside the admin API
no supervision — lifecycle belongs to Docker compose or systemd

Each one is a separate concern composed with a separate tool.

threat model

Non-cooperating clients fail closed. crackbox run puts the workload on a Docker network with no default route; clients that ignore HTTPS_PROXY simply can’t reach anything off-network. Setting HTTPS_PROXY="" doesn’t help — there’s no other path out.

Most tooling honors proxy environment variables natively: curl, wget, pip, npm, git, go, apt. Node’s fetch needs a one-line shim to set the global agent. That’s the only common gotcha.

Trust assumption: source IP within the daemon’s network is honest. The topology has to be such that only your workload can reach the proxy on its registered IP. crackbox run arranges this with a private Docker network. In service deployments you arrange it yourself.

admin API

The daemon exposes an HTTP control plane on the admin listener (default :3129):

POST /v1/register — body {"ip": "...", "id": "...", "allowlist": ["host1", "host2"]}
POST /v1/unregister — body {"ip": "..."}
GET /v1/state — current registry as JSON
GET /health — liveness + TCP self-test against the proxy listener; returns 503 {"status":"proxy_down"} if the proxy port is dead

Bearer-token auth on mutating endpoints when CRACKBOX_ADMIN_SECRET is set; /v1/state and /health stay open. Empty secret leaves mutations unauthenticated and logs a warning.

library

Go consumers can import the daemon’s packages directly:

import "github.com/.../crackbox/pkg/admin"   // Registry, API
import "github.com/.../crackbox/pkg/proxy"   // forward + transparent
import "github.com/.../crackbox/pkg/client"  // admin HTTP client

The CLI is the primary surface. The library is exported but not promised stable across point releases; pin the import path to a tag.