deploy/runner: enforce actions egress allowlist

Status	File	+	-
M	`deploy/ansible/inventory/production.example`	3	1
M	`deploy/ansible/roles/shithubd-runner/defaults/main.yml`	9	3
M	`deploy/ansible/roles/shithubd-runner/handlers/main.yml`	6	0
M	`deploy/ansible/roles/shithubd-runner/tasks/main.yml`	91	2
M	`deploy/runner-config/README.md`	10	10
M	`deploy/runner-config/dnsmasq.conf.j2`	14	6
A	`deploy/runner-config/firewall.sh.j2`	26	0
A	`deploy/systemd/shithub-runner-firewall.service`	14	0
M	`deploy/systemd/shithubd-runner.service`	2	1
M	`docs/internal/runbooks/actions-runner.md`	12	4
M	`docs/internal/runbooks/runner-deploy.md`	22	15

deploy/ansible/inventory/production.examplemodified

  # shithub_runner_labels=self-hosted,linux,ubuntu-latest
  # shithub_runner_capacity=1
  # shithub_runner_default_image=ghcr.io/shithub/runner-nix:1.0
--# shithub_runner_dns_servers=172.30.0.1
++# The role creates shithub-actions on shact0 (172.30.0.1/24), runs
++# dnsmasq on that bridge, and enforces direct-IP egress denial with
++# shithub-runner-firewall.service.

deploy/ansible/roles/shithubd-runner/defaults/main.ymlmodified

    - "*.githubusercontent.com"
  shithub_runner_engine: docker
  shithub_runner_default_image: ghcr.io/shithub/runner-nix:1.0
--shithub_runner_network: bridge
++shithub_runner_network: shithub-actions
--shithub_runner_dns_servers: []
++shithub_runner_network_bridge: shact0
--shithub_runner_dnsmasq_config: /etc/shithubd-runner/dnsmasq.conf
++shithub_runner_network_subnet: 172.30.0.0/24
++shithub_runner_network_gateway: 172.30.0.1
++shithub_runner_dns_servers:
++  - "{{ shithub_runner_network_gateway }}"
++shithub_runner_dnsmasq_config: /etc/dnsmasq.d/shithubd-runner.conf
  shithub_runner_dnsmasq_upstream: 1.1.1.1
++shithub_runner_ipset_name: shithub_actions_allowed
++shithub_runner_firewall_script: /usr/local/sbin/shithub-runner-firewall
  shithub_runner_memory: 2g
  shithub_runner_cpus: "2"
  shithub_runner_seccomp_profile: /etc/shithubd-runner/seccomp.json

deploy/ansible/roles/shithubd-runner/handlers/main.ymlmodified

  - name: daemon-reload
    systemd: { daemon_reload: yes }
++- name: restart dnsmasq
++  systemd: { name: dnsmasq, state: restarted, enabled: yes }
++
++- name: restart shithub-runner-firewall
++  systemd: { name: shithub-runner-firewall, state: restarted, enabled: yes, daemon_reload: yes }
++
  - name: restart shithubd-runner
    systemd: { name: shithubd-runner, state: restarted, enabled: yes }

deploy/ansible/roles/shithubd-runner/tasks/main.ymlmodified

        unless the shithubd-runner systemd unit's ReadWritePaths= hardening is
        updated with the matching path.
++- name: Runner Docker bridge name fits Linux interface limit
++  assert:
++    that:
++      - (shithub_runner_network_bridge | string | length) <= 15
++    fail_msg: >-
++      shithub_runner_network_bridge must be 15 characters or fewer because
++      Linux interface names are capped by IFNAMSIZ.
++
  - name: Docker group exists
    getent:
      database: group
      key: docker
    when: shithub_runner_engine == "docker"
++- name: Runner network firewall packages
++  apt:
++    name:
++      - dnsmasq
++      - ipset
++      - iptables
++    state: present
++    update_cache: yes
++  when: shithub_runner_engine == "docker"
++
  - name: Runner group
    group:
      name: shithub-runner
      - { path: "{{ shithub_runner_workspace_root }}", owner: shithub-runner, group: shithub-runner, mode: "0750" }
      - { path: /var/lib/shithubd-runner/binaries, owner: shithub-runner, group: shithub-runner, mode: "0750" }
++- name: Inspect Actions Docker network
++  command: "{{ shithub_runner_engine }} network inspect {{ shithub_runner_network }}"
++  register: shithub_runner_network_inspect
++  failed_when: shithub_runner_network_inspect.rc not in [0, 1]
++  changed_when: false
++  when: shithub_runner_engine == "docker" and not ansible_check_mode
++
++- name: Create Actions Docker network
++  command: >-
++    {{ shithub_runner_engine }} network create
++    --driver bridge
++    --subnet {{ shithub_runner_network_subnet }}
++    --gateway {{ shithub_runner_network_gateway }}
++    --opt com.docker.network.bridge.name={{ shithub_runner_network_bridge }}
++    {{ shithub_runner_network }}
++  when:
++    - shithub_runner_engine == "docker"
++    - not ansible_check_mode
++    - shithub_runner_network_inspect.rc == 1
++
++- name: Inspect Actions Docker network after converge
++  command: "{{ shithub_runner_engine }} network inspect {{ shithub_runner_network }}"
++  register: shithub_runner_network_final
++  changed_when: false
++  when: shithub_runner_engine == "docker" and not ansible_check_mode
++
++- name: Record Actions Docker network facts
++  set_fact:
++    shithub_runner_network_info: "{{ (shithub_runner_network_final.stdout | from_json)[0] }}"
++  when: shithub_runner_engine == "docker" and not ansible_check_mode
++
++- name: Actions Docker network matches runner firewall config
++  assert:
++    that:
++      - shithub_runner_network_info.Driver == "bridge"
++      - shithub_runner_network_info.Options["com.docker.network.bridge.name"] == shithub_runner_network_bridge
++      - shithub_runner_network_info.IPAM.Config[0].Subnet == shithub_runner_network_subnet
++      - shithub_runner_network_info.IPAM.Config[0].Gateway == shithub_runner_network_gateway
++    fail_msg: >-
++      Existing Docker network {{ shithub_runner_network }} does not match the
++      configured Actions subnet/gateway/bridge. Remove or rename the network
++      before re-running the role so firewall rules target the correct bridge.
++  when: shithub_runner_engine == "docker" and not ansible_check_mode
++
  - name: Upload shithubd-runner binary (built by `make build` locally)
    copy:
      src: "{{ playbook_dir }}/../../bin/shithubd-runner"
      src: "{{ playbook_dir }}/../runner-config/dnsmasq.conf.j2"
      dest: "{{ shithub_runner_dnsmasq_config }}"
      owner: root
--    group: shithub-runner
++    group: root
--    mode: "0640"
++    mode: "0644"
++  notify: restart dnsmasq
++
++- name: Runner firewall script
++  template:
++    src: "{{ playbook_dir }}/../runner-config/firewall.sh.j2"
++    dest: "{{ shithub_runner_firewall_script }}"
++    owner: root
++    group: root
++    mode: "0755"
++  notify: restart shithub-runner-firewall
++
++- name: Runner firewall systemd unit
++  copy:
++    src: "{{ playbook_dir }}/../systemd/shithub-runner-firewall.service"
++    dest: /etc/systemd/system/shithub-runner-firewall.service
++    mode: "0644"
++  notify: [daemon-reload, restart shithub-runner-firewall]
++
++- name: Enable + start runner firewall
++  systemd:
++    name: shithub-runner-firewall
++    state: started
++    enabled: yes
++    daemon_reload: yes
++
++- name: Enable + start runner dnsmasq
++  systemd: { name: dnsmasq, state: started, enabled: yes }
  - name: Runner systemd unit
    copy:

deploy/runner-config/README.mdmodified

  Update this file deliberately when changing Docker daemon versions or
  runner syscall posture.
--`dnsmasq.conf.j2` is the optional runner DNS allowlist template. The
++`dnsmasq.conf.j2` is the runner DNS allowlist template. The Ansible
--Ansible role renders it to `/etc/shithubd-runner/dnsmasq.conf` from
++role renders it to `/etc/dnsmasq.d/shithubd-runner.conf` from
--`shithub_runner_network_allowlist`; operators can run dnsmasq bound to
++`shithub_runner_network_allowlist`, binds dnsmasq to the dedicated
--their Actions Docker bridge and point step containers at it with
++Actions Docker bridge, and points step containers at that resolver
--`engine.dns_servers`.
++with `engine.dns_servers`.
--The dnsmasq template intentionally has no default upstream resolver, so
++`firewall.sh.j2` is installed as `/usr/local/sbin/shithub-runner-firewall`
--names outside the allowlist fail resolution. DNS allowlisting alone does
++and run by `shithub-runner-firewall.service`. It creates the ipset used
--not block direct-IP egress or a workflow that brings its own resolver;
++by dnsmasq and rejects direct-IP egress from the Actions bridge unless
--pair it with host firewall rules on the runner bridge for a deny-by-
++the destination IP was populated by an allowlisted DNS response. DNS to
--default network boundary.
++the bridge resolver is the only DNS path allowed from step containers.

deploy/runner-config/dnsmasq.conf.j2modified

--# Managed by Ansible. Optional DNS allowlist resolver for Actions runners.
++# Managed by Ansible. DNS allowlist resolver for Actions runners.
--#
++# Bound only to the dedicated Actions Docker bridge; dnsmasq inserts
--# Pair this with a Docker bridge/network that uses this resolver as its only
++# successful allowlisted resolutions into the ipset enforced by
--# DNS server. This controls name resolution, not direct-IP egress; enforce
++# shithub-runner-firewall.service.
--# direct-IP denial with host firewall rules on the runner bridge.
++interface={{ shithub_runner_network_bridge }}
++listen-address={{ shithub_runner_network_gateway }}
++bind-interfaces
  domain-needed
  bogus-priv
  no-resolv
  no-hosts
--{% for pattern in shithub_runner_network_allowlist %}
++{% if shithub_runner_network_allowlist is string %}
++{% set allowlist = shithub_runner_network_allowlist.split(",") | map("trim") | list %}
++{% else %}
++{% set allowlist = shithub_runner_network_allowlist %}
++{% endif %}
++{% for pattern in allowlist %}
  {% set host = (pattern[2:] if pattern.startswith("*.") else pattern) %}
  server=/{{ host }}/{{ shithub_runner_dnsmasq_upstream }}
++ipset=/{{ host }}/{{ shithub_runner_ipset_name }}
  {% endfor %}

deploy/runner-config/firewall.sh.j2added

++#!/bin/sh
++# Managed by Ansible. Enforces deny-by-default egress for the Actions bridge.
++set -eu
++
++IPSET="{{ shithub_runner_ipset_name }}"
++CHAIN="SHITHUB_ACTIONS_EGRESS"
++SUBNET="{{ shithub_runner_network_subnet }}"
++DNS="{{ shithub_runner_network_gateway }}"
++
++IPSET_BIN="${IPSET_BIN:-ipset}"
++IPTABLES="${IPTABLES:-iptables}"
++
++"$IPSET_BIN" create "$IPSET" hash:ip family inet timeout 86400 -exist
++
++"$IPTABLES" -w -N "$CHAIN" 2>/dev/null || true
++"$IPTABLES" -w -F "$CHAIN"
++"$IPTABLES" -w -A "$CHAIN" -m conntrack --ctstate ESTABLISHED,RELATED -j ACCEPT
++"$IPTABLES" -w -A "$CHAIN" -d "$DNS" -p udp --dport 53 -j ACCEPT
++"$IPTABLES" -w -A "$CHAIN" -d "$DNS" -p tcp --dport 53 -j ACCEPT
++"$IPTABLES" -w -A "$CHAIN" -m set --match-set "$IPSET" dst -j ACCEPT
++"$IPTABLES" -w -A "$CHAIN" -j REJECT
++
++while "$IPTABLES" -w -D FORWARD -s "$SUBNET" -j "$CHAIN" 2>/dev/null; do
++    :
++done
++"$IPTABLES" -w -I FORWARD 1 -s "$SUBNET" -j "$CHAIN"

deploy/systemd/shithub-runner-firewall.serviceadded

++[Unit]
++Description=shithub Actions runner firewall
++After=network-online.target docker.service
++Wants=network-online.target
++Requires=docker.service
++Before=shithubd-runner.service
++
++[Service]
++Type=oneshot
++ExecStart=/usr/local/sbin/shithub-runner-firewall
++RemainAfterExit=yes
++
++[Install]
++WantedBy=multi-user.target

deploy/systemd/shithubd-runner.servicemodified


 [Unit]
 Description=shithub Actions runner
+After=network-online.target docker.service dnsmasq.service shithub-runner-firewall.service
 Wants=network-online.target docker.service
+Requires=dnsmasq.service shithub-runner-firewall.service
 
 [Service]
 Type=simple

docs/internal/runbooks/actions-runner.mdmodified

  Prereqs:
--- Database migrations are current through `0053_runner_jwt_used.sql`.
++- Database migrations are current through `0055_workflow_job_secret_masks.sql`.
  - `SHITHUB_TOTP_KEY` or `auth.totp_key_b64` is set on the web process.
  - Object storage is configured if testing artifact upload.
  - Docker or Podman is installed on the runner host.
    --server-url "$BASE" \
    --token "$RUNNER_TOKEN" \
    --labels self-hosted,linux,ubuntu-latest \
--  --workspace-root /var/lib/shithubd-runner/workspaces
++  --workspace-root /var/lib/shithubd-runner/workspaces \
++  --network shithub-actions \
++  --dns-servers 172.30.0.1
  ```
  Equivalent config file:
  [engine]
  kind = "docker"
  default_image = "ghcr.io/shithub/runner-nix:1.0"
--network = "bridge"
++network = "shithub-actions"
  memory = "2g"
  cpus = "2"
  seccomp_profile = "/etc/shithubd-runner/seccomp.json"
  user = "65534:65534"
  pids_limit = 512
--dns_servers = []
++dns_servers = ["172.30.0.1"]
  ```
  The config path defaults to `/etc/shithubd-runner/config.toml`.
  Environment variables use the `SHITHUB_RUNNER_` prefix, for example
  `SHITHUB_RUNNER_TOKEN` or `SHITHUB_RUNNER_SERVER__BASE_URL`.
++The Ansible runner role creates the `shithub-actions` bridge, runs the
++allowlist resolver at `172.30.0.1`, and installs firewall rules that
++reject direct-IP egress from step containers. If you run the binary
++without the role, provision equivalent network controls before pointing
++workflows at the runner.
++
  ## Curl token smoke
  Claim a job:

docs/internal/runbooks/runner-deploy.mdmodified

  shithub_runner_seccomp_profile=/etc/shithubd-runner/seccomp.json
  shithub_runner_container_user=65534:65534
  shithub_runner_pids_limit=512
--shithub_runner_dns_servers=172.30.0.1
  ```
  The role writes non-secret config to
  `shithub_runner_network_allowlist` defaults to GitHub source/archive
  hosts plus Docker Hub registry hosts. Override it when a runner must
--fetch from an internal package registry. `shithub_runner_dns_servers`
++fetch from an internal package registry. The role creates the
--is empty by default; set it only after a DNS allowlist resolver exists
++`shithub-actions` Docker bridge at `172.30.0.1/24`, runs dnsmasq on
--on the runner network.
++that bridge, and sets `engine.dns_servers` to the bridge resolver by
++default.
  ## Deploy
  - creates the `shithub-runner` system user and joins it to `docker`
  - uploads `/usr/local/bin/shithubd-runner`
  - renders `/etc/shithubd-runner/config.toml` and `runner.env`
--- renders `/etc/shithubd-runner/dnsmasq.conf` from the network
++- creates the dedicated Actions Docker network and bridge
--  allowlist for operators who run a local DNS allowlist resolver
++- renders `/etc/dnsmasq.d/shithubd-runner.conf` from the network
++  allowlist and starts dnsmasq bound to the Actions bridge
++- installs `shithub-runner-firewall.service`, which rejects direct-IP
++  egress from step containers unless dnsmasq populated the destination
++  in the allowlist ipset
  - installs the pinned seccomp profile at
    `/etc/shithubd-runner/seccomp.json`
  - installs `deploy/systemd/shithubd-runner.service`
  Expected state:
  - the UID check prints `65534`
++- a workflow-level request for `permissions: {shithub-runner-root: write}`
++  still runs as `65534`; root opt-in is disabled in the shipped runner
++  config until a trusted-workflow policy exists
  - writing under `/etc` fails because the root filesystem is read-only
  - `mount` fails because the container does not have `CAP_SYS_ADMIN`
  - step logs and systemd journal include the configured image, network,
    Docker `--dns`.
  For a single-host deployment, create a dedicated Docker bridge for
--Actions jobs, run dnsmasq bound to that bridge, render
++Actions jobs, run dnsmasq bound to that bridge, and set
--`/etc/shithubd-runner/dnsmasq.conf`, and set
  `shithub_runner_dns_servers` to the bridge address of that resolver.
--The rendered dnsmasq config has no default upstream resolver; names not
++The Ansible role now does this by default. The rendered dnsmasq config
--matching the allowlist fail DNS resolution.
++has no default upstream resolver; names not matching the allowlist fail
--
++DNS resolution.
--DNS filtering is not a complete egress boundary by itself. Block
++
--direct-IP egress from the Actions bridge with host firewall rules, and
++The firewall service closes the direct-IP bypass: containers on the
--allow only DNS to the resolver plus established outbound connections
++Actions subnet may send DNS only to the bridge resolver, and other
--opened by that resolver. Keep the runner on a separate host from web
++egress is allowed only when the destination IP is present in the
++dnsmasq-populated ipset. Keep the runner on a separate host from web
  and database services.
  ## Rollback

tenseleyflow/shithub / `eb28d6f`

11 changed files

`@@ -1,7 +1,8 @@`
1	[Unit]	1	[Unit]
2	Description=shithub Actions runner	2	Description=shithub Actions runner
3	-After=network-online.target docker.service	3	+After=network-online.target docker.service dnsmasq.service shithub-runner-firewall.service
4	Wants=network-online.target docker.service	4	Wants=network-online.target docker.service
		5	+Requires=dnsmasq.service shithub-runner-firewall.service
5		6
6	[Service]	7	[Service]
7	Type=simple	8	Type=simple