saarCTF Vulnbox Build Tool

Vulnbox images are automatically generated by Packer and run docker or VirtualBox

Images are based on Debian 12 (Bookworm).

Subsequent builds can be speed up by installing apt-cacher-ng on the host: apt-get install -y apt-cacher-ng.

What is here

• Scripts to build a vulnbox including services that follow the saarCTF service template
• Scripts to build a testbox (similar to vulnbox but with a simple test service only)
• Scripts to build a "router VM"
• Scripts to convert any of there .ova VM images to a .tar.xz cloud bundle or cloud image (see below)

How to build the vulnbox

• Step 0.1: Download and install Packer, Docker and optionally VirtualBox.

  • Note: Packer from debian apt repos is too old to be used here (04/2024)

• Step 0.2: Run poetry install

• Step 1: Create a project: copy a folder in projects/ and edit the vulnbuild.yaml. Add your service repos here.

• Step 2: Prepare services

  All services in projects/<your-project>/services are included. They must be structured following these guidelines. Use poetry run vulnbuild project=<your-project> clone to clone pre-configured repos. Use poetry run vulnbuild project=<your-project> pull-service pull-gamelib to update services.

• Step 3: Build the vulnbox

  These targets might be a good start. Vulnbuild only builds missing targets or ones with changed dependencies. poetry run vulnbuild project=<your-project> vm:vulnbox poetry run vulnbuild project=<your-project> vm:router vm:testbox vm:vulnbox:7z vm:vulnbox:cloudbundle:gpg vm:vulnbox:cloudbundle:hetzner

Vulnbuild Tool

Think of the vulnbuild tool as a big Makefile, which builds targets including their dependencies. You can see all possible targets: poetry run vulnbuild project=saarctf-2023 list --all

Some important commands are:

• poetry run vulnbuild project=saarctf-2023 list --all (see all targets)
• poetry run vulnbuild project=saarctf-2023 clone (clone all configured services)
• poetry run vulnbuild project=saarctf-2023 pull-service pull-gamelib (update all services and their gamelibs to current master)
• poetry run vulnbuild project=saarctf-2023 service:xyz (build a single service)
• poetry run vulnbuild project=saarctf-2023 vm:vulnbox --force (build the vulbox)
• poetry run vulnbuild project=saarctf-2023 vm:vulnbox:cloudbundle:hetzner (build orga-hosted image)
• poetry run vulnbuild project=saarctf-2023 upload (build and upload all targets from your config)
• poetry run vulnbuild project=saarctf-2023 clean [service:xyz] [vm:vulnbox] (remove build outputs)
• poetry run vulnbuild project=saarctf-2023 pull-service pull-gamelib upload vm:vulnbox:cloudbundle:hetzner (build everything for a CTF - if you're lucky)

Customizing the vulnbox

• Each project gets a fresh SSH key and encryption password (in output//)
• The greeting frontpage can be edited in /frontpage and /frontpage-testbox.
• The general structure of build steps is in projects/default/scripts.
  • Scripts can be in projects/default/scripts or projects/<your-project>/scripts
  • Executed are files from scripts/, scripts/<builder/, scripts/<target>/, and scripts/<target>-<builder>, where builder is e.g. virtualbox, and target is e.g. vulnbox
  • Scripts with the same filename override each other, more specialized variants are preferred

Cloud builds

We can convert any of these VMs into a .tar.xz bundle that is suited for cloud hosting. These bundles are our hacky way to get cloud images, which we came up with due to the COVID-19 outbreak. Please read the setup instructions on ctf.saarland to get an idea what these bundles are.

To build a bundle from an existing ova VM image, run: poetry run vulnbuild project=... vm:vulnbox:cloudbundle

Conversion will ask for root (sudo), libguestfs-tools must be installed and all VirtualBox VMs must be powered off.

Orga-hosted cloud images

Building a cloud-image for orga-hosted Hetzner Cloud is easy.

1. First build the regular vulnbox and the cloud bundle as described above.
2. HCLOUD_TOKEN=... poetry run vulnbuild project=... vm:vulnbox:cloudbundle:hetzner

The manual way (deprecated)

If you (optionally) host vulnboxes as organizer, we provide Hetzner cloud images. These cloud images come with WireGuard preinstalled that connects to the game network. Use cloudinit to provide SSH keys, root password and /etc/wireguard/vulnbox.conf. Include sed '/^root/s/:0:0:99999:/:1:0:99999:/' -i /etc/shadow in cloudinit's runcmd to get rid of some "password reset" issues.

1. First build the regular vulnbox and the cloud bundle as described above.
2. Create a new Hetzner Cloud Server (Debian), boot it into rescue mode.
3. Upload the cloud bundle archive and the scripts from /cloudhosting-scripts to /dev/shm on that machine.
4. Run /dev/shm/install_bundle_for_orgahosted_cloud.sh <uploaded-archive.tar.xz>
5. Shutdown the server and take a snapshot. This snapshot is your image.

Hosting Vulnboxes (for test)

Virtualbox boxes: Try utils/import_vm.sh.

• ./utils/import_vm.sh output/.../router/router.ova router-team5 intteam5
• ./utils/import_vm.sh output/.../testbox/testbox.ova testbox-team5 intteam5
• ./utils/import_vm.sh output/.../vulnbox/vulnbox.ova vulnbox-team5 intteam5

intteam5 is an internal network, other options are vboxnetX and eth1. Router has an additional interface for outgoing connections, its SSH is accessible on host's port 22222.

For docker-based boxes:

• Import: docker import output/workshop/docker-image-vulnbox.tar vulnbox:latest
• Hosting: utils/docker-compose.yml

To test the image and gameserver locally, try:

• PROJECT_NAME=... ./checkers-run.sh <IP>
• PROJECT_NAME=... ./exploits-run.sh <IP>