docker-compose.yml

# The lab.
#
#   docker compose up -d
#   open http://localhost:8099
#
# Docker is the only prerequisite. There is no host toolchain here: the control
# server is a service in this stack, the certificate authority is generated by
# that server into a volume, and the coordination server is the lab's own.
#
# THE SHAPE OF IT
#
# Four machines, each on its own segment behind its own router, all meeting on
# one shared segment that stands in for the public internet. The isolation is
# the point: it is what makes NAT traversal real here rather than decorative,
# and a lab where every machine is already on one flat wire teaches the
# opposite of chapter 01.
#
#   lan-ubuntu 10.0.13.0/24  --[ nat-ubuntu 203.0.113.13 ]--\
#   lan-roam   10.0.27.0/24  --[ nat-roam   203.0.113.27 ]---+-- wan 203.0.113.0/24
#   lan-evil   10.0.66.0/24  --[ nat-evil   203.0.113.66 ]--/       |
#                                                                  |- headscale 203.0.113.2
#                                                                  |- lab-vps   203.0.113.11
#
# lab-vps has a public address of its own, because that is the whole of its
# problem. Everything else is behind something.

name: srag-lab

x-node: &node
  build:
    context: ./images/node
  # tailscaled runs on a real TUN device and puts real WireGuard frames on the
  # wire. Nothing here is userspace networking.
  devices: ["/dev/net/tun:/dev/net/tun"]
  cap_add: ["NET_ADMIN", "NET_RAW"]
  # /proc/sys is read-only inside a container, so forwarding has to be turned on
  # by the runtime rather than by the entrypoint. lab-vps needs it for the
  # published-port trap; the others simply do not use it.
  sysctls:
    net.ipv4.ip_forward: 1
  restart: unless-stopped
  extra_hosts:
    - "headscale:203.0.113.2"
    # There is no DNS in this lab and tailcat addresses carry a hostname, not
    # an address. Both ends have to resolve the relay to the same name the
    # certificate was minted for or the TLS handshake fails, which is the
    # correct failure and a baffling one to debug.
    - "derp.lab.internal:203.0.113.3"
  environment:
    LAB_LOGIN_SERVER: "https://headscale:8443"
    LAB_DERP_HOSTNAME: "derp.lab.internal"
    LAB_STATE_DIR: "/lab/state"
  volumes:
    - labstate:/lab/state
  depends_on:
    headscale:
      condition: service_started

services:

  # ---- the control surface ------------------------------------------------
  # Holds the Docker socket, so it is published to loopback and refuses to
  # start if that is changed. It also generates the lab's CA before anything
  # else boots, which is why headscale waits on its health check.
  control:
    build:
      context: ./control
    container_name: control
    restart: unless-stopped
    ports:
      - "127.0.0.1:8099:8099"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - labstate:/lab/state
    environment:
      LAB_ADDR: "0.0.0.0:8099"
      LAB_STATE_DIR: "/lab/state"
    healthcheck:
      test: ["CMD", "/control", "-health"]
      interval: 2s
      timeout: 3s
      retries: 30
      start_period: 2s
    networks:
      ctl:

  # ---- coordination server, and the lab's own DERP relay ------------------
  headscale:
    image: headscale/headscale:0.29.3
    container_name: headscale
    restart: unless-stopped
    command: ["serve"]
    depends_on:
      control:
        condition: service_healthy
    volumes:
      - ./config/headscale/config.yaml:/etc/headscale/config.yaml:ro
      - labstate:/lab/state
      - hsdata:/var/lib/headscale
    networks:
      wan:
        ipv4_address: 203.0.113.2

  # ---- the relay with nothing behind it — chapter 01 ----------------------
  # Headscale's embedded DERP serves the tailnet and still does. This second
  # relay serves tailcat, which cannot use that one: a tailcat address built
  # from a hostname dials :443, and headscale's relay answers on :8443 next to
  # the coordination API.
  #
  # The mechanical reason is the smaller one. This relay holds no policy, no
  # node keys and no expiry dates, because derper has nowhere to put them, and
  # that is the property under test: tailcat's packets must not pass through
  # the container holding the control plane, or the one claim chapter 01 makes
  # about tailcat would be untestable in the one place a reader checks it.
  #
  # It is on `wan` and nothing else. images/derp/Dockerfile has the rest.
  derp:
    build:
      context: ./images/derp
    container_name: derp
    hostname: derp.lab.internal
    restart: unless-stopped
    depends_on:
      control:
        condition: service_healthy
    environment:
      LAB_STATE_DIR: "/lab/state"
      LAB_DERP_HOSTNAME: "derp.lab.internal"
    # A relay is not a router, and this is the one container in the lab that
    # sits on the shared segment without a reason to forward anything. Turning
    # it off costs nothing and makes the answer to "did adding this open a way
    # off the host" a setting somebody can read rather than an argument.
    sysctls:
      net.ipv4.ip_forward: 0
    volumes:
      - labstate:/lab/state:ro
    networks:
      wan:
        ipv4_address: 203.0.113.3

  # ---- the public box — chapter 08 ---------------------------------------
  lab-vps:
    <<: *node
    container_name: lab-vps
    hostname: lab-vps
    environment:
      LAB_ROLE: "vps"
      LAB_HOSTNAME: "lab-vps"
      LAB_LOGIN_SERVER: "https://headscale:8443"
      LAB_STATE_DIR: "/lab/state"
      LAB_DERP_HOSTNAME: "derp.lab.internal"
    # A machine keeps its identity across a restart. Without this the node key
    # is regenerated every time the container is recreated and the coordination
    # server ends up holding a graveyard of stale registrations.
    volumes:
      - labstate:/lab/state
      - ts-vps:/var/lib/tailscale
    networks:
      wan:
        ipv4_address: 203.0.113.11
      vpslan:
        ipv4_address: 10.0.11.2

  # The container behind the published port. Reachable only through lab-vps,
  # and only when you turn the trap on.
  lab-vps-web:
    image: nginx:alpine
    container_name: lab-vps-web
    restart: unless-stopped
    networks:
      vpslan:
        ipv4_address: 10.0.11.20

  # ---- the laptop — chapter 09 -------------------------------------------
  nat-ubuntu:
    build: { context: ./images/nat }
    container_name: nat-ubuntu
    restart: unless-stopped
    cap_add: ["NET_ADMIN", "NET_RAW"]
    sysctls:
      net.ipv4.ip_forward: 1
    environment:
      NAT_LAN_SUBNET: "10.0.13.0/24"
      NAT_MODE: "easy"
    networks:
      wan:
        ipv4_address: 203.0.113.13
      lan-ubuntu:
        ipv4_address: 10.0.13.254

  lab-ubuntu:
    <<: *node
    container_name: lab-ubuntu
    hostname: lab-ubuntu
    environment:
      LAB_ROLE: "ubuntu"
      LAB_HOSTNAME: "lab-ubuntu"
      LAB_GATEWAY: "10.0.13.254"
      LAB_LOGIN_SERVER: "https://headscale:8443"
      LAB_STATE_DIR: "/lab/state"
      LAB_DERP_HOSTNAME: "derp.lab.internal"
    volumes:
      - labstate:/lab/state
      - ts-ubuntu:/var/lib/tailscale
    networks:
      lan-ubuntu:
        ipv4_address: 10.0.13.2

  # ---- the roaming client — chapters 03 and 04 ---------------------------
  # NAT_MODE=hard: a fresh source port per destination, so hole punching cannot
  # complete and this machine falls back to the relay. That is not a handicap
  # for its own sake — it is what a phone on mobile data actually gets.
  nat-roam:
    build: { context: ./images/nat }
    container_name: nat-roam
    restart: unless-stopped
    cap_add: ["NET_ADMIN", "NET_RAW"]
    sysctls:
      net.ipv4.ip_forward: 1
    environment:
      NAT_LAN_SUBNET: "10.0.27.0/24"
      NAT_MODE: "hard"
    networks:
      wan:
        ipv4_address: 203.0.113.27
      lan-roam:
        ipv4_address: 10.0.27.254

  lab-roam:
    <<: *node
    container_name: lab-roam
    hostname: lab-roam
    environment:
      LAB_ROLE: "roam"
      LAB_HOSTNAME: "lab-roam"
      LAB_GATEWAY: "10.0.27.254"
      LAB_LOGIN_SERVER: "https://headscale:8443"
      LAB_STATE_DIR: "/lab/state"
      LAB_DERP_HOSTNAME: "derp.lab.internal"
    volumes:
      - labstate:/lab/state
      - ts-roam:/var/lib/tailscale
    networks:
      lan-roam:
        ipv4_address: 10.0.27.2

  # ---- the attacker — opt in, always -------------------------------------
  # profiles: ["attack"] means these two do not exist unless you ask for them.
  # `docker compose --profile attack up -d`, or `make attack`.
  nat-evil:
    build: { context: ./images/nat }
    container_name: nat-evil
    profiles: ["attack"]
    restart: unless-stopped
    cap_add: ["NET_ADMIN", "NET_RAW"]
    sysctls:
      net.ipv4.ip_forward: 1
    environment:
      NAT_LAN_SUBNET: "10.0.66.0/24"
      NAT_MODE: "easy"
    networks:
      wan:
        ipv4_address: 203.0.113.66
      lan-evil:
        ipv4_address: 10.0.66.254

  evil-box:
    build:
      context: ./images/evil
    container_name: evil-box
    hostname: evil-box
    profiles: ["attack"]
    restart: unless-stopped
    depends_on:
      control:
        condition: service_healthy
    devices: ["/dev/net/tun:/dev/net/tun"]
    cap_add: ["NET_ADMIN", "NET_RAW"]
    extra_hosts:
      - "headscale:203.0.113.2"
      - "derp.lab.internal:203.0.113.3"
    sysctls:
      net.ipv4.ip_forward: 1
    environment:
      LAB_GATEWAY: "10.0.66.254"
      LAB_DERP_HOSTNAME: "derp.lab.internal"
      LAB_STATE_DIR: "/lab/state"
      LAB_ONPATH_SUBNET: "10.0.13.0/24"
    volumes:
      - labstate:/lab/state
      - ts-evil:/var/lib/tailscale
    networks:
      lan-evil:
        ipv4_address: 10.0.66.2
      # The optional shared segment. Being on it is not the same as being
      # on-path: nothing routes through evil-box until you press the switch.
      lan-ubuntu:
        ipv4_address: 10.0.13.66

  # ---- the four named configurations -------------------------------------
  # `docker compose --profile weak up` builds a stack that should score what
  # the sandbox says it scores. When it does not, that gap is the most
  # interesting bug this project can produce. Each of these runs the same code
  # the button in the UI runs, then exits.
  cfg-day-one:
    build: { context: ./control }
    container_name: cfg-day-one
    profiles: ["day-one"]
    command: ["-apply", "day-one"]
    restart: "no"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - labstate:/lab/state
    networks: { ctl: }

  cfg-typical:
    build: { context: ./control }
    container_name: cfg-typical
    profiles: ["typical"]
    command: ["-apply", "typical"]
    restart: "no"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - labstate:/lab/state
    networks: { ctl: }

  cfg-weak:
    build: { context: ./control }
    container_name: cfg-weak
    profiles: ["weak"]
    command: ["-apply", "weak"]
    restart: "no"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - labstate:/lab/state
    networks: { ctl: }

  cfg-hardened:
    build: { context: ./control }
    container_name: cfg-hardened
    profiles: ["hardened"]
    command: ["-apply", "hardened"]
    restart: "no"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - labstate:/lab/state
    networks: { ctl: }

networks:
  # The segment standing in for the public internet. Documentation addresses
  # (RFC 5737), so nothing here can be confused for a real host.
  wan:
    ipam:
      config: [{ subnet: 203.0.113.0/24 }]
  lan-ubuntu:
    ipam:
      config: [{ subnet: 10.0.13.0/24 }]
  lan-roam:
    ipam:
      config: [{ subnet: 10.0.27.0/24 }]
  lan-evil:
    ipam:
      config: [{ subnet: 10.0.66.0/24 }]
  # lab-vps's own container bridge: the one it routes for when a published
  # port punches through its firewall.
  #
  # 10.0.11.0/24 for two reasons. It is the address chapter 14's sandbox
  # already gives lab-vps (assets/sandbox.js: lan "10.0.11.2"), so the lab and
  # the model agree rather than diverging over a detail nobody would think to
  # check. And it is out of the way: Docker hands out 172.17-172.31 and
  # 192.168.x by default, so a fixed subnet in there collides on any machine
  # with a few compose projects on it.
  vpslan:
    ipam:
      config: [{ subnet: 10.0.11.0/24 }]
  # The control server sits on its own network and talks to Docker, not to the
  # lab. Nothing in the lab is attached here, so nothing in the lab can reach
  # it. It is deliberately not `internal: true` — Docker will not publish a port
  # for a container on an internal network, and the loopback publish is the one
  # thing that has to work.
  ctl:

volumes:
  labstate:
  hsdata:
  ts-vps:
  ts-ubuntu:
  ts-roam:
  ts-evil: