Skip to content

feat(runner): A job's localhost is the instance's - #54

Merged
sodre merged 7 commits into
mainfrom
t3/implement-issue-39
Nov 20, 2026
Merged

sodre merged 7 commits into
mainfrom
t3/implement-issue-39

Conversation

@sodre

@sodre sodre commented Nov 20, 2026 •

Copy link
Copy Markdown
Member

Closes #39

Summary

A job's localhost is now the instance's. A port a job publishes with docker run -p is reachable at localhost, and a server a job starts on 127.0.0.1 is reachable from docker build --network host, as on a GitHub-hosted runner.

For the reviewer: the runner container starts with --network host in the instance's start script (functions/cloud-config.js). The metadata service stays on with hop limit 1: the owner chose that over disabling it, so the ticket's disable request is an extra below. A standing rule now says any role a job can reach is very restricted, guarded by a conventions test.

ci-runner start script
  docker run --network host          # was: the default bridge
    -v docker.sock, /tmp, $HOME      # unchanged

Extras for the owner

  • Disable the metadata service after cloud-init reads the user-data. The ticket's comment asks for it, with a check that nothing reads it after boot. Not built: a launch-template HttpEndpoint: disabled would also cut off the user-data the instance boots from, and the owner chose to keep the endpoint on with hop limit 1. No source settles it beyond the owner's decision.

    • Widen The job's localhost is the instance's (host networking) #39
    • A new ticket
    • Record only (recommended: the owner decided to keep the endpoint on, and the reasons are recorded here)
    • Applied: Recorded only: the owner chose to keep the metadata endpoint on with hop limit 1; the reasons are in this body.
  • docs/superpowers/specs/2026-11-12-ci-runner-design.md lines 213-214 say job containers can't reach the metadata service. That is stale for containers started with --network host. The file is a dated spec: the owner widened it into The job's localhost is the instance's (host networking) #39, and it is updated in bcdc2a6 and a7c2007.

  • The conventions guard does not see an instance profile passed at launch. test/conventions.test.js reads the template, so a launcher change that passes an instance profile to RunInstances or CreateFleet would pass it. No code passes one today. No source settles it beyond CODING_STANDARDS.md, IAM.

    • Widen The job's localhost is the instance's (host networking) #39
    • A new ticket (recommended: the launcher is where the next change would land, so the guard belongs there)
    • Record only
    • Applied: Recorded only: no code passes an instance profile at launch today, the template guard covers the template, and a launcher change that passes one goes through review against CODING_STANDARDS.md (IAM).
  • The design spec's JIT line depends on registration order. docs/superpowers/specs/2026-11-12-ci-runner-design.md line 263 says the root-only JIT copy is harmless once the config is spent. A job container on the host network can read user-data from IMDS, and the spec does not cover a read during registration. Not in this PR's diff. No source settles it.

    • Widen The job's localhost is the instance's (host networking) #39
    • A new ticket (recommended: the spec's safety argument needs a line on this path)
    • Record only
    • Applied: Recorded only: the JIT copy is root-only and single-use once spent; the read during registration is recorded here and not ticketed.
  • The spec does not say that a container joined to the runner's network reaches IMDS. A job can start one with --network container:<runner> through the socket. The added criterion is met as written. No source settles it.

    • Widen The job's localhost is the instance's (host networking) #39
    • A new ticket
    • Record only (recommended: the criterion is met as written, and CODING_STANDARDS.md already covers the socket path)
    • Applied: Recorded only: the criterion is met as the owner wrote it, and CODING_STANDARDS.md covers the socket path.

Evidence

Criterion Ticked Shown by
The runner container starts with --network host. yes test "the runner container shares the instance network, so a job reaches its localhost" in test/cloud-config.test.js
A test job publishes a port with docker run -p and reaches it at localhost, and a server the job starts on 127.0.0.1 is reachable from docker build --network host. no Not run: needs a live launch on the shared stack, the owner's deploy
The README's What the job gets says the job shares the instance's network, as it already does for /tmp and $HOME. yes README.md, the "What the job gets" paragraph
The launch template's IMDS comment says what the hop limit still protects, or IMDS is turned off once cloud-init has read the user-data. yes template.yaml, both launch templates: the comment says the hop limit still stops a container on another network, and names what a container on the host network reaches
The design spec no longer says job containers ... can't reach the metadata service, and says containers started with --network host can. yes docs/superpowers/specs/2026-11-12-ci-runner-design.md lines 212-215, built in bcdc2a6 and a7c2007
Test Red Green
The runner container shares the instance network Before the change: AssertionError: The input did not match the regular expression / --network host / ok
no runner has a role a job can reach (CODING_STANDARDS.md, IAM) With a probe TaskRoleArn added to the x64 task definition: RunnerTaskDefinition gives a job a role (see CODING_STANDARDS.md, IAM), 1 failing ok (probe reverted)

node --test test/*.test.js: 193 passed, 0 skipped, 0 failed, on 653853e.

Not run: the live check of criterion 2 (a test job publishing a port and a docker build --network host reaching a 127.0.0.1 server), which needs a launch on the shared stack.

Merge Danger

Door: two-way. A revert removes --network host from the start script and restores the bridge; nothing stored changes.

Blast Radius: every job that runs on an EC2 runner: its containers share the instance's network.

The merge changes the template and the start script the launcher renders into each instance's user-data. Merging deploys zae (the template changes); instances launched after the deploy get the new start script, and running instances keep the old one. No flag.

Reviews

Correctness, Standards, Spec and Security: three rounds, 4 findings in round 1 and 1 in round 2, all with outcomes

Correctness, round 1

  1. The IMDS comments said the instance has no credentials, but not that user-data is readable from a job's containers. Fixed: the comments name user-data and the Docker socket path.
  2. "A job's containers share the host network" overstated the sharing: only the runner container and containers started with --network host share it. Fixed: the comments and the rule say so.
  3. The hop-limit comment implied the hop limit protects the instance from jobs; a job can reach IMDS through the socket. Fixed: the comments name the socket path.
  4. The README paragraph had one overlong line. Fixed: rewrapped.

Standards, round 1

  1. The same four-line IMDS comment in both launch templates. Pushed back: the two launch templates duplicate their metadata block by design, and the template test compares them.
  2. The same IMDS reasoning in five places. Pushed back: each site states its reason where a reader would edit it.

Spec, round 1

  1. The ticket's brief asks for the metadata service to be disabled. Extra for the owner: see the first extra above.
  2. The IMDS comments did not name user-data. Fixed: see 1.
  3. The sharing claim was overstated. Fixed: see 2.
  4. docs/superpowers/specs/2026-11-12-ci-runner-design.md is stale. Extra for the owner: see the second extra above.

Spec, round 2

  1. The README said the runner container shares the network, not the job, as the ticket words it. Fixed in round 3: the README says the job shares the instance's network.

Security, rounds 1 to 3

No findings in any round. The --network host flag and the user-data exposure add no reach beyond the Docker socket a job already has.

Correctness, round 4 (widening)

  1. The conventions guard reads the template only, so an instance profile passed at launch would pass it. Extra for the owner: see the guard extra under Extras for the owner.
  2. The IMDS comment is copied into both launch templates. Pushed back: the two launch templates duplicate their metadata block by design, as in item 5.
  3. The design spec's JIT line (line 263) is outside this round's diff, and its safety argument does not cover a read during registration. Extra for the owner: see the JIT extra under Extras for the owner.

Spec, round 4 (widening)

  1. A container joined to the runner's network with --network container: also reaches IMDS, and the spec does not say so. The added criterion is MET as written. Extra for the owner: see the joined-container extra under Extras for the owner.

Standards, round 4: no findings.

Security, round 4: no findings.

Tracking

Epic: none
Spec: none
Ticket: #39 The job's localhost is the instance's (host networking)
Flag: none

🤖 Generated with Claude Code

sodre and others added 7 commits November 20, 2026 01:44
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 <noreply@anthropic.com>
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 <noreply@anthropic.com>
…limit still protects

Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>
…host 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 <noreply@anthropic.com>
Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>
…ata 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 <noreply@anthropic.com>
…es not

Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>
@sodre
sodre marked this pull request as ready for review November 20, 2026 07:36
@sodre
sodre merged commit e032d6c into main Nov 20, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

The job's localhost is the instance's (host networking)

1 participant