From bc5edbd846265697ef509dd1fcacb604e982e852 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Patrick=20Sodr=C3=A9?= Date: Fri, 20 Nov 2026 01:44:24 -0500 Subject: [PATCH 1/7] feat(cloud-config): the runner container shares the instance's network A job's localhost is the instance's, so a port published with docker run -p, and a server the job starts on 127.0.0.1 for docker build --network host, are reachable as on a GitHub-hosted runner. The README says so, and the launch template's metadata comment no longer claims the hop limit keeps job containers off IMDS. Co-Authored-By: Claude Haiku 5.5 --- README.md | 5 ++++- functions/cloud-config.js | 2 +- template.yaml | 6 ++++-- test/cloud-config.test.js | 8 ++++++++ 4 files changed, 17 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 2018001..6f908ba 100644 --- a/README.md +++ b/README.md @@ -111,7 +111,10 @@ the host's Docker daemon, so a `docker run -v` source is a path on the host. `/tmp` and the runner's home (`/home/runner`: `$HOME`, and the work directory `_work` with the checkout and `$RUNNER_TEMP`) are at the same paths on both, so a bind mount from any of them works as it does on a GitHub-hosted runner, -`mktemp` files and `~/` config included. Both are on the 50 GB root disk. A mount from anywhere else (`/opt`, +`mktemp` files and `~/` config included. Both are on the 50 GB root disk. The job's +containers share the instance's network, so `localhost` is the instance's: a port a +job publishes with `docker run -p` is reachable at `localhost`, and a server it starts +on `127.0.0.1` is reachable from `docker build --network host`, as on a GitHub-hosted runner. A mount from anywhere else (`/opt`, `/etc`, `/var`) gets an empty host path. Nothing is pinned: every boot pulls `:latest`, and the image is rebuilt weekly, for linux/amd64 and linux/arm64, each built and smoke-tested on its own native runner. diff --git a/functions/cloud-config.js b/functions/cloud-config.js index 7c34b4b..71fa23a 100644 --- a/functions/cloud-config.js +++ b/functions/cloud-config.js @@ -43,7 +43,7 @@ docker run --rm --user 0 --entrypoint cp -v ${HOME_DIR}:/seed ${image} -a ${HOME install -d -m 1777 /var/tmp/ci-runner mount --bind /var/tmp/ci-runner /tmp || exit 1 -docker run -d --init --name ci-runner \\ +docker run -d --init --name ci-runner --network host \\ -v /var/run/docker.sock:/var/run/docker.sock \\ -v /tmp:/tmp \\ -v ${HOME_DIR}:${HOME_DIR} \\ diff --git a/template.yaml b/template.yaml index caf288c..892bc7d 100644 --- a/template.yaml +++ b/template.yaml @@ -739,7 +739,8 @@ Resources: BlockDeviceMappings: - DeviceName: /dev/xvda Ebs: { VolumeSize: 50, VolumeType: gp3, DeleteOnTermination: true, Encrypted: true } - # IMDSv2 only, one hop: a job's containers can't reach the metadata service. + # IMDSv2 only, one hop. The runner container shares the instance's network + # (--network host), so the hop limit no longer keeps a job's containers off the metadata service. MetadataOptions: HttpEndpoint: enabled HttpTokens: required @@ -766,7 +767,8 @@ Resources: BlockDeviceMappings: - DeviceName: /dev/xvda Ebs: { VolumeSize: 50, VolumeType: gp3, DeleteOnTermination: true, Encrypted: true } - # IMDSv2 only, one hop: a job's containers can't reach the metadata service. + # IMDSv2 only, one hop. The runner container shares the instance's network + # (--network host), so the hop limit no longer keeps a job's containers off the metadata service. MetadataOptions: HttpEndpoint: enabled HttpTokens: required diff --git a/test/cloud-config.test.js b/test/cloud-config.test.js index 6707870..a1cdea5 100644 --- a/test/cloud-config.test.js +++ b/test/cloud-config.test.js @@ -30,6 +30,14 @@ test('a job sees /tmp and its home at the same paths as the host docker daemon', assert.match(out, /ghcr\.io\/zeroae\/ci-runner:latest \.\/run\.sh --jitconfig /); }); +test('the runner container shares the instance network, so a job reaches its localhost', () => { + // A port a job publishes with `docker run -p`, and a server it starts on + // 127.0.0.1 for `docker build --network host`, are on the instance's loopback. + const out = renderCloudConfig({ jitConfig: JIT }); + const run = out.slice(out.indexOf('docker run -d'), out.indexOf('./run.sh')); + assert.match(run, / --network host /); +}); + test('the host home is seeded from the image before it is mounted over the runner', () => { // The image keeps the runner itself in /home/runner; an empty host dir // mounted there would hide run.sh. From 7dc78c2fd76785108a58fc31111e865060c3419f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Patrick=20Sodr=C3=A9?= Date: Fri, 20 Nov 2026 01:56:05 -0500 Subject: [PATCH 2/7] test(conventions): no runner has a role a job can reach A job's containers share the instance's network, so an instance profile would be reachable from them through IMDS, and a task role reaches them the same way. CODING_STANDARDS.md now requires any such role to be very restricted, and the guard fails until the owner has approved one. Co-Authored-By: Claude Haiku 5.5 --- CODING_STANDARDS.md | 9 +++++++++ test/conventions.test.js | 12 ++++++++++++ 2 files changed, 21 insertions(+) diff --git a/CODING_STANDARDS.md b/CODING_STANDARDS.md index d7852bf..1809b79 100644 --- a/CODING_STANDARDS.md +++ b/CODING_STANDARDS.md @@ -32,3 +32,12 @@ Grant the least the function does, scoped by the stack's tag (`ci-runner:stack`) or its own resources, never `*` on a write action without a condition. A new condition is checked live: some EC2 calls don't carry the keys their docs suggest (see `docs/traps.md`). + +A role a job can reach, a task role or an instance profile, is **very +restricted**: it names each action it needs, never `*`, grants no IAM action +and no `iam:PassRole`, and writes only to the stack's own resources. Adding one +changes a security control, so it goes to the owner first. Today none exists: +a job finds no AWS credentials, and `test/conventions.test.js` keeps it so. +On EC2 the instance metadata service is reachable from a job's containers +(they share the host network), so an instance profile would hand its +credentials to any job. diff --git a/test/conventions.test.js b/test/conventions.test.js index 02f72e1..27cccdf 100644 --- a/test/conventions.test.js +++ b/test/conventions.test.js @@ -38,6 +38,18 @@ test('every IAM role and policy is PowerUserPB-${AWS::StackName}-*, and every ro assert.match(read('Makefile'), /--capabilities CAPABILITY_NAMED_IAM/); }); +test('no runner has a role a job can reach (CODING_STANDARDS.md, IAM)', () => { + // A job's containers share the instance's network, so IMDS would hand an + // instance profile to any job; a task role reaches a job the same way. Adding + // one is a security-control change for the owner first, so this fails until it is made. + const runners = resources.filter((r) => ['AWS::ECS::TaskDefinition', 'AWS::EC2::LaunchTemplate'].includes(r.type)); + assert.ok(runners.length >= 3, 'the runner task definitions and launch templates'); + for (const r of runners) { + assert.doesNotMatch(r.body, /TaskRoleArn|IamInstanceProfile/, `${r.name} gives a job a role (see CODING_STANDARDS.md, IAM)`); + } + assert.ok(!resources.some((r) => r.type === 'AWS::IAM::InstanceProfile'), 'an instance profile (see CODING_STANDARDS.md, IAM)'); +}); + // Read but deliberately not set by the template: a test or hand-run override. const OPTIONAL_ENV = new Set(['IDLE_SECONDS']); From 90346dfd45186f7de417b18ba9f631ff020818d6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Patrick=20Sodr=C3=A9?= Date: Fri, 20 Nov 2026 01:57:02 -0500 Subject: [PATCH 3/7] docs(template): the launch template's IMDS comment says what the hop limit still protects Co-Authored-By: Claude Haiku 5.5 --- template.yaml | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/template.yaml b/template.yaml index 892bc7d..e0183c4 100644 --- a/template.yaml +++ b/template.yaml @@ -739,8 +739,10 @@ Resources: BlockDeviceMappings: - DeviceName: /dev/xvda Ebs: { VolumeSize: 50, VolumeType: gp3, DeleteOnTermination: true, Encrypted: true } - # IMDSv2 only, one hop. The runner container shares the instance's network - # (--network host), so the hop limit no longer keeps a job's containers off the metadata service. + # IMDSv2 only, one hop. It still stops a container on another network from + # reaching the metadata service. The runner container shares the instance's + # network (--network host), so a job's containers can reach it; the instance + # has no profile, so IMDS holds no credentials (CODING_STANDARDS.md, IAM). MetadataOptions: HttpEndpoint: enabled HttpTokens: required @@ -767,8 +769,10 @@ Resources: BlockDeviceMappings: - DeviceName: /dev/xvda Ebs: { VolumeSize: 50, VolumeType: gp3, DeleteOnTermination: true, Encrypted: true } - # IMDSv2 only, one hop. The runner container shares the instance's network - # (--network host), so the hop limit no longer keeps a job's containers off the metadata service. + # IMDSv2 only, one hop. It still stops a container on another network from + # reaching the metadata service. The runner container shares the instance's + # network (--network host), so a job's containers can reach it; the instance + # has no profile, so IMDS holds no credentials (CODING_STANDARDS.md, IAM). MetadataOptions: HttpEndpoint: enabled HttpTokens: required From 5857abb8cf3b555d5a92eeff13e8012b789a632e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Patrick=20Sodr=C3=A9?= Date: Fri, 20 Nov 2026 02:05:14 -0500 Subject: [PATCH 4/7] docs: IMDS comments name user-data and the socket path; a job's localhost is the runner's The review round found that the comments said the instance has no credentials (true) but not that user-data is readable from a job's containers, and that only the runner container and containers started with --network host share the host network, not every job container. Co-Authored-By: Claude Haiku 5.5 --- CODING_STANDARDS.md | 7 ++++--- README.md | 11 ++++++----- template.yaml | 14 ++++++++------ test/conventions.test.js | 5 +++-- 4 files changed, 21 insertions(+), 16 deletions(-) diff --git a/CODING_STANDARDS.md b/CODING_STANDARDS.md index 1809b79..5c0f83c 100644 --- a/CODING_STANDARDS.md +++ b/CODING_STANDARDS.md @@ -38,6 +38,7 @@ restricted**: it names each action it needs, never `*`, grants no IAM action and no `iam:PassRole`, and writes only to the stack's own resources. Adding one changes a security control, so it goes to the owner first. Today none exists: a job finds no AWS credentials, and `test/conventions.test.js` keeps it so. -On EC2 the instance metadata service is reachable from a job's containers -(they share the host network), so an instance profile would hand its -credentials to any job. +The runner container shares the instance's network, and a job can start a +container that does too through the Docker socket, so a job reaches the +instance metadata service; an instance profile would hand its credentials to +any job. diff --git a/README.md b/README.md index 6f908ba..baaad37 100644 --- a/README.md +++ b/README.md @@ -111,11 +111,12 @@ the host's Docker daemon, so a `docker run -v` source is a path on the host. `/tmp` and the runner's home (`/home/runner`: `$HOME`, and the work directory `_work` with the checkout and `$RUNNER_TEMP`) are at the same paths on both, so a bind mount from any of them works as it does on a GitHub-hosted runner, -`mktemp` files and `~/` config included. Both are on the 50 GB root disk. The job's -containers share the instance's network, so `localhost` is the instance's: a port a -job publishes with `docker run -p` is reachable at `localhost`, and a server it starts -on `127.0.0.1` is reachable from `docker build --network host`, as on a GitHub-hosted runner. A mount from anywhere else (`/opt`, -`/etc`, `/var`) gets an empty host path. Nothing is pinned: every boot pulls +`mktemp` files and `~/` config included. Both are on the 50 GB root disk. The runner +container shares the instance's network, so a job's `localhost` is the instance's: a +port a job publishes with `docker run -p` is reachable at `localhost`, and a server it +starts on `127.0.0.1` is reachable from `docker build --network host`, as on a +GitHub-hosted runner. A mount from anywhere else (`/opt`, `/etc`, `/var`) gets an +empty host path. Nothing is pinned: every boot pulls `:latest`, and the image is rebuilt weekly, for linux/amd64 and linux/arm64, each built and smoke-tested on its own native runner. diff --git a/template.yaml b/template.yaml index e0183c4..710e2bf 100644 --- a/template.yaml +++ b/template.yaml @@ -740,9 +740,10 @@ Resources: - DeviceName: /dev/xvda Ebs: { VolumeSize: 50, VolumeType: gp3, DeleteOnTermination: true, Encrypted: true } # IMDSv2 only, one hop. It still stops a container on another network from - # reaching the metadata service. The runner container shares the instance's - # network (--network host), so a job's containers can reach it; the instance - # has no profile, so IMDS holds no credentials (CODING_STANDARDS.md, IAM). + # reaching IMDS. The runner container shares the instance's network, and so + # does any container a job starts with --network host through the Docker + # socket: they reach IMDS, and the user-data (the JIT config) with it. The + # instance has no profile, so IMDS holds no credentials (CODING_STANDARDS.md, IAM). MetadataOptions: HttpEndpoint: enabled HttpTokens: required @@ -770,9 +771,10 @@ Resources: - DeviceName: /dev/xvda Ebs: { VolumeSize: 50, VolumeType: gp3, DeleteOnTermination: true, Encrypted: true } # IMDSv2 only, one hop. It still stops a container on another network from - # reaching the metadata service. The runner container shares the instance's - # network (--network host), so a job's containers can reach it; the instance - # has no profile, so IMDS holds no credentials (CODING_STANDARDS.md, IAM). + # reaching IMDS. The runner container shares the instance's network, and so + # does any container a job starts with --network host through the Docker + # socket: they reach IMDS, and the user-data (the JIT config) with it. The + # instance has no profile, so IMDS holds no credentials (CODING_STANDARDS.md, IAM). MetadataOptions: HttpEndpoint: enabled HttpTokens: required diff --git a/test/conventions.test.js b/test/conventions.test.js index 27cccdf..22bccff 100644 --- a/test/conventions.test.js +++ b/test/conventions.test.js @@ -39,8 +39,9 @@ test('every IAM role and policy is PowerUserPB-${AWS::StackName}-*, and every ro }); test('no runner has a role a job can reach (CODING_STANDARDS.md, IAM)', () => { - // A job's containers share the instance's network, so IMDS would hand an - // instance profile to any job; a task role reaches a job the same way. Adding + // A job can run a container on the instance's network (the runner's own, or one + // it starts through the socket), so IMDS would hand an instance profile to any + // job; a task role reaches a job the same way. Adding // one is a security-control change for the owner first, so this fails until it is made. const runners = resources.filter((r) => ['AWS::ECS::TaskDefinition', 'AWS::EC2::LaunchTemplate'].includes(r.type)); assert.ok(runners.length >= 3, 'the runner task definitions and launch templates'); From 653853e0e7a03fe5dc3cae7b88c6915ab8a963b3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Patrick=20Sodr=C3=A9?= Date: Fri, 20 Nov 2026 02:08:56 -0500 Subject: [PATCH 5/7] docs(README): the job shares the instance's network, as the ticket says Co-Authored-By: Claude Haiku 5.5 --- README.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index baaad37..0f115a6 100644 --- a/README.md +++ b/README.md @@ -111,12 +111,12 @@ the host's Docker daemon, so a `docker run -v` source is a path on the host. `/tmp` and the runner's home (`/home/runner`: `$HOME`, and the work directory `_work` with the checkout and `$RUNNER_TEMP`) are at the same paths on both, so a bind mount from any of them works as it does on a GitHub-hosted runner, -`mktemp` files and `~/` config included. Both are on the 50 GB root disk. The runner -container shares the instance's network, so a job's `localhost` is the instance's: a -port a job publishes with `docker run -p` is reachable at `localhost`, and a server it -starts on `127.0.0.1` is reachable from `docker build --network host`, as on a -GitHub-hosted runner. A mount from anywhere else (`/opt`, `/etc`, `/var`) gets an -empty host path. Nothing is pinned: every boot pulls +`mktemp` files and `~/` config included. Both are on the 50 GB root disk. The job shares +the instance's network, as it does for `/tmp` and `$HOME`: its `localhost` is the +instance's, so a port it publishes with `docker run -p` is reachable at `localhost`, +and a server it starts on `127.0.0.1` is reachable from `docker build --network host`, +as on a GitHub-hosted runner. A mount from anywhere else (`/opt`, `/etc`, `/var`) gets +an empty host path. Nothing is pinned: every boot pulls `:latest`, and the image is rebuilt weekly, for linux/amd64 and linux/arm64, each built and smoke-tested on its own native runner. From bcdc2a6e038f557cb4c41576bff37e727dd25e10 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Patrick=20Sodr=C3=A9?= Date: Fri, 20 Nov 2026 02:30:19 -0500 Subject: [PATCH 6/7] docs(spec): a container started with --network host reaches the metadata service The design spec said the containers a job starts can't reach IMDS. A container started with --network host shares the instance's network, so it can. Widened into #39 by the owner. Co-Authored-By: Claude Haiku 5.5 --- docs/superpowers/specs/2026-11-12-ci-runner-design.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/superpowers/specs/2026-11-12-ci-runner-design.md b/docs/superpowers/specs/2026-11-12-ci-runner-design.md index c961a79..18dac76 100644 --- a/docs/superpowers/specs/2026-11-12-ci-runner-design.md +++ b/docs/superpowers/specs/2026-11-12-ci-runner-design.md @@ -211,7 +211,8 @@ IPv4 address. with that spread. - 50 GB gp3 root volume, deleted on termination. - **IMDSv2 required, hop limit 1**, so the Docker containers a job starts - can't reach the instance metadata service. + can't reach the instance metadata service, unless it is started with + `--network host`: that shares the instance's network, and reaches it. - `InstanceInitiatedShutdownBehavior: terminate`. - **Caps:** at most **6 Spot and 2 On-Demand** CI runners at once, across all repos, counted by tag. It is a soft cap: two launches at the same moment may From a7c2007372130084e54b20a9ca7f0fbd5c582791 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Patrick=20Sodr=C3=A9?= Date: Fri, 20 Nov 2026 02:30:45 -0500 Subject: [PATCH 7/7] docs(spec): the bridge blocks the metadata service; --network host does not Co-Authored-By: Claude Haiku 5.5 --- docs/superpowers/specs/2026-11-12-ci-runner-design.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/superpowers/specs/2026-11-12-ci-runner-design.md b/docs/superpowers/specs/2026-11-12-ci-runner-design.md index 18dac76..740bb53 100644 --- a/docs/superpowers/specs/2026-11-12-ci-runner-design.md +++ b/docs/superpowers/specs/2026-11-12-ci-runner-design.md @@ -210,9 +210,9 @@ IPv4 address. overrides or `CreateFleet` of type `instant`; whatever launches one instance with that spread. - 50 GB gp3 root volume, deleted on termination. -- **IMDSv2 required, hop limit 1**, so the Docker containers a job starts - can't reach the instance metadata service, unless it is started with - `--network host`: that shares the instance's network, and reaches it. +- **IMDSv2 required, hop limit 1**: a Docker container a job starts on the + default bridge can't reach the instance metadata service. One started with + `--network host` shares the instance's network, and can. - `InstanceInitiatedShutdownBehavior: terminate`. - **Caps:** at most **6 Spot and 2 On-Demand** CI runners at once, across all repos, counted by tag. It is a soft cap: two launches at the same moment may