Command line

vulnboxd comes as three binaries:

• vulnboxd is the daemon. systemd runs it; you rarely start it by hand.
• vulnboxctl is everything else: installing, setting up a box, upgrading, running compose for a service, rolling back and watching.
• vulnboxd-pcap is the capture broker, which runs as its own service.

vulnboxd and vulnboxctl take the same options:

option
-c, --config <FILE>	config file (default /etc/vulnboxd/config.yml); defaults are used if it does not exist
--services-dir <DIR>	overrides services_dir from the config file
-h, --help	print help
-V, --version	print the version

vulnboxd-pcap takes -c, -h and -V, but not --services-dir: it has no services.

Log verbosity is set with the RUST_LOG environment variable, for example RUST_LOG=debug. The default is info.

vulnboxd

sudo vulnboxd -c /etc/vulnboxd/config.yml

Runs the daemon: discovers services, deploys them, proxies their ports and watches them. See How it works.

vulnboxd-pcap

vulnboxd-pcap [-c <FILE>] [--cmd <COMMAND>] [--listen <ADDR>]

Captures traffic and serves it over PCAP-over-IP, using the config's pcap section. systemd runs it as vulnboxd-pcap; you rarely start it by hand. See Capturing traffic.

option
--cmd <COMMAND>	capture command, instead of the config's. Also read from PCAP_COMMAND
--listen <ADDR>	where readers connect, instead of the config's. Also read from LISTEN_ADDRESS

The two environment variables are the ones fox-it's pcap-broker reads, so a unit written for that one works here.

vulnboxctl setup-interactive

vulnboxctl setup-interactive

The same as init, with a terminal wizard that asks for every setting first and shows each service's progress. Needs an interactive terminal.

export GITHUB_TOKEN=ghp_...
sudo -E vulnboxctl setup-interactive

vulnboxctl init

vulnboxctl init [--install]

Prepares a vulnbox without asking anything: a git repository per service, pushed to a private GitHub repository with its own deploy key, the capture tools' configuration, and vulnboxd's own config. It reads its settings from the config file and the token from GITHUB_TOKEN.

option
--install	also install and start vulnboxd, as vulnboxctl install does

Safe to run again: it only does what is left, and a failed service can be fixed and retried without touching the others. Exits non-zero if any service failed. See Getting started for the steps.

vulnboxctl install

vulnboxctl install [OPTIONS] [SERVICES_DIR]

Installs vulnboxd on this box: both binaries into /usr/local/bin, a config for the services directory, the systemd unit and the compose guard, then starts it and checks it came up. Needs root.

option
SERVICES_DIR	one directory per service, each with a compose file; defaults to the config's, or /srv
--tick <DURATION>	tick length of the game, such as 60s
--window <DURATION>	the end of each tick vulnboxd restarts services in, such as 5s
--poll <DURATION>	how often git is checked for new commits
--no-start	install everything, but do not start vulnboxd yet
--force	replace an existing config

The positional SERVICES_DIR and the global --services-dir do the same thing; the positional one wins if both are given.

Run it again to repair an installation. An existing config is kept unless --force is given.

vulnboxctl upgrade

vulnboxctl upgrade [FROM]... [--now] [--pcap] [--version <TAG>] [--repo <OWNER/NAME>]

Installs a new build and asks the running daemon to take it up, which it does without closing a port. Needs root. See Upgrading.

FROM is a release archive, a directory holding the build, or the binaries themselves under any name — they are identified by what they answer to --version. With no FROM it fetches a release from GitHub and checks it against its SHA-256.

option
--now	take the new build up as soon as nothing is being deployed, rather than at the end-of-tick window
--pcap	replace vulnboxd-pcap too, which restarts it and interrupts the capture
--version <TAG>	release to fetch; the latest by default. Only when fetching from GitHub
--repo <OWNER/NAME>	repository to fetch from, instead of the config's upgrade.repo

A private repository needs a token that can read it, in upgrade.token or the VULNBOXD_UPGRADE_TOKEN environment variable.

vulnboxctl compose

vulnboxctl compose <SERVICE> [ARGS]...

Runs docker compose for a service with vulnboxd's port override applied, passing every argument after the service name through. It replaces itself with docker compose, so the terminal, exit status and Ctrl+C behave exactly as they would with docker compose itself.

sudo vulnboxctl compose web ps
sudo vulnboxctl compose web logs -f --tail 100
sudo vulnboxctl compose web exec app sh

vulnboxctl rollback

vulnboxctl rollback <SERVICE>

Undoes the latest change to a service, its code or its rules, whichever came last, with a commit that is pushed. The running daemon picks it up like any other change: rules within a second, code at the end of the tick. Running it twice undoes the rollback. See Rollback.

vulnboxctl top

vulnboxctl top

Alias: vulnboxctl dashboard.

A terminal dashboard of the running daemon: services, ports and whether they answer, open connections and how often each rule fires. ↑/↓ select a service, r refreshes, q quits.

It reads the daemon's metrics endpoint, so it needs metrics left on; with metrics: null there is nothing for it to read.