feat: US-017 - Add SSH port forwarding / tunneling e2e-docker fixture

Author: NathanFlurry

packages/secure-exec/tests/e2e-docker.test.ts

@@ -24,6 +24,7 @@ import {
 import { createTestNodeRuntime } from "./test-utils.js";
 import {
 	buildImage,
+	getContainerInternalIp,
 	skipUnlessDocker,
 	startContainer,
 	type Container,
@@ -111,6 +112,9 @@ const skipReason = isCI ? false : skipUnlessDocker();
 
 const activeContainers: Container[] = [];
 let services: ServiceConnections = {};
+let internalAddresses: Partial<
+	Record<ServiceName, { host: string; port: number }>
+> = {};
 
 /* ------------------------------------------------------------------ */
 /*  Fixture discovery (runs at module load)                            */
@@ -144,6 +148,12 @@ describe.skipIf(skipReason)("e2e-docker", () => {
 					port: Number(process.env.SSH_PORT ?? 2222),
 				},
 			};
+			internalAddresses = {
+				redis: {
+					host: process.env.REDIS_INTERNAL_HOST ?? "127.0.0.1",
+					port: Number(process.env.REDIS_INTERNAL_PORT ?? 6379),
+				},
+			};
 			return;
 		}
 
@@ -212,6 +222,15 @@ describe.skipIf(skipReason)("e2e-docker", () => {
 			redis: { host: redis.host, port: redis.port },
 			ssh: { host: ssh.host, port: ssh.port },
 		};
+
+		// Internal Docker bridge IPs for tunnel tests (SSH container can reach
+		// other containers on the same bridge by their internal IP)
+		internalAddresses = {
+			redis: {
+				host: getContainerInternalIp(redis.containerId),
+				port: 6379,
+			},
+		};
 	}, 180_000);
 
 	afterAll(() => {
@@ -289,10 +308,16 @@ function getServiceEnvVars(
 				env.MYSQL_HOST = conn.host;
 				env.MYSQL_PORT = String(conn.port);
 				break;
-			case "redis":
+			case "redis": {
 				env.REDIS_HOST = conn.host;
 				env.REDIS_PORT = String(conn.port);
+				const internal = internalAddresses.redis;
+				if (internal) {
+					env.REDIS_INTERNAL_HOST = internal.host;
+					env.REDIS_INTERNAL_PORT = String(internal.port);
+				}
 				break;
+			}
 			case "ssh":
 				env.SSH_HOST = conn.host;
 				env.SSH_PORT = String(conn.port);

packages/secure-exec/tests/e2e-docker/ssh2-tunnel/fixture.json

@@ -0,0 +1,5 @@
+{
+	"entry": "src/index.js",
+	"expectation": "pass",
+	"services": ["ssh", "redis"]
+}

packages/secure-exec/tests/e2e-docker/ssh2-tunnel/package.json

@@ -0,0 +1,8 @@
+{
+	"name": "e2e-docker-ssh2-tunnel",
+	"private": true,
+	"type": "commonjs",
+	"dependencies": {
+		"ssh2": "1.17.0"
+	}
+}

packages/secure-exec/tests/e2e-docker/ssh2-tunnel/src/index.js

@@ -0,0 +1,78 @@
+const { Client } = require("ssh2");
+
+async function main() {
+	const tunnelHost = process.env.REDIS_INTERNAL_HOST;
+	const tunnelPort = Number(process.env.REDIS_INTERNAL_PORT || "6379");
+
+	if (!tunnelHost) {
+		throw new Error("REDIS_INTERNAL_HOST is required for tunnel test");
+	}
+
+	const result = await new Promise((resolve, reject) => {
+		const conn = new Client();
+		let settled = false;
+
+		conn.on("ready", () => {
+			// Open a tunnel through the SSH server to Redis
+			conn.forwardOut(
+				"127.0.0.1",
+				0,
+				tunnelHost,
+				tunnelPort,
+				(err, stream) => {
+					if (err) {
+						conn.end();
+						return reject(err);
+					}
+
+					let response = "";
+
+					stream.on("data", (data) => {
+						response += data.toString();
+						// Redis PING response is "+PONG\r\n"
+						if (!settled && response.includes("\r\n")) {
+							settled = true;
+							conn.end();
+							resolve({
+								tunneled: true,
+								response: response.trim(),
+							});
+						}
+					});
+
+					stream.on("error", (streamErr) => {
+						if (!settled) {
+							settled = true;
+							conn.end();
+							reject(streamErr);
+						}
+					});
+
+					// Send Redis PING command (inline format)
+					stream.write("PING\r\n");
+				},
+			);
+		});
+
+		conn.on("error", (err) => {
+			if (!settled) {
+				settled = true;
+				reject(err);
+			}
+		});
+
+		conn.connect({
+			host: process.env.SSH_HOST,
+			port: Number(process.env.SSH_PORT),
+			username: "testuser",
+			password: "testpass",
+		});
+	});
+
+	console.log(JSON.stringify(result));
+}
+
+main().catch((err) => {
+	console.error(err.message);
+	process.exit(1);
+});

packages/secure-exec/tests/utils/docker.ts

@@ -78,6 +78,17 @@ export interface Container {
 /**
  * Build a Docker image from a Dockerfile and tag it.
  */
+/**
+ * Return a container's internal IP on the Docker bridge network.
+ */
+export function getContainerInternalIp(containerId: string): string {
+	return execFileSync(
+		"docker",
+		["inspect", containerId, "-f", "{{.NetworkSettings.IPAddress}}"],
+		{ encoding: "utf-8", timeout: 5_000 },
+	).trim();
+}
+
 export function buildImage(dockerfilePath: string, tag: string): void {
 	if (!isDockerAvailable()) {
 		throw new Error("Docker is not available on this host");

progress.txt

@@ -3,6 +3,7 @@ Started: 2026-03-17
 PRD: ralph/kernel-hardening (46 stories)
 
 ## Codebase Patterns
+- Docker containers on default bridge can reach each other by internal IP (docker inspect IPAddress), not by 127.0.0.1 host-mapped ports — use getContainerInternalIp() for cross-container tunnel destinations
 - process.exit() inside bridge callbacks (childProcessDispatch, timer refs) causes unhandled ProcessExitError — always await a Promise from the callback, then call process.exit() at the top-level await
 - Bridge process.stdout.write strips trailing newlines — NDJSON capture helpers must join with '\n' to restore event delimiters
 - Native binary sandbox test pattern: createTestNodeRuntime + createHostCommandExecutor, sandbox code calls require('child_process').spawn(), env vars serialize through bridge JSON to host executor
@@ -2658,3 +2659,40 @@ PRD: ralph/kernel-hardening (46 stories)
   - Claude Code's SDK (sdk.mjs) is not a standalone runner; it always spawns cli.js as a subprocess with native .node dependencies
   - OpenCode is a compiled Bun ELF binary — no JS source to extract
 ---
+
+## 2026-03-19 - US-016
+- Added SSH key-based authentication e2e-docker fixture
+- Generated test RSA keypair (test_rsa/test_rsa.pub) embedded in fixture and Dockerfile
+- Updated sshd.Dockerfile: enabled PubkeyAuthentication, COPY test_rsa.pub to authorized_keys
+- New fixture ssh2-key-auth connects with privateKey instead of password, runs conn.exec(), verifies parity
+- Files changed:
+  - packages/secure-exec/tests/e2e-docker/dockerfiles/sshd.Dockerfile (added pubkey auth + COPY)
+  - packages/secure-exec/tests/e2e-docker/dockerfiles/test_rsa.pub (new)
+  - packages/secure-exec/tests/e2e-docker/ssh2-key-auth/fixture.json (new)
+  - packages/secure-exec/tests/e2e-docker/ssh2-key-auth/package.json (new)
+  - packages/secure-exec/tests/e2e-docker/ssh2-key-auth/src/index.js (new)
+  - packages/secure-exec/tests/e2e-docker/ssh2-key-auth/keys/test_rsa (new)
+  - packages/secure-exec/tests/e2e-docker/ssh2-key-auth/keys/test_rsa.pub (new)
+- **Learnings for future iterations:**
+  - buildImage() uses path.dirname(dockerfilePath) as build context — public keys for COPY must be in the dockerfiles/ directory
+  - RSA key-based auth works through the sandbox crypto bridge without any additional fixes — sign()/createSign() already handle RSA key parsing
+  - Fixture pattern for key auth: read privateKey via fs.readFileSync, pass as Buffer to conn.connect({ privateKey })
+---
+
+## 2026-03-19 - US-017
+- Added SSH port forwarding / tunneling e2e-docker fixture
+- Fixture connects via SSH, uses conn.forwardOut() to tunnel to Redis container, sends raw PING, verifies +PONG response
+- Test infra discovers container internal IPs on Docker bridge via `docker inspect` for cross-container tunnel destinations
+- Files changed:
+  - packages/secure-exec/tests/e2e-docker/ssh2-tunnel/fixture.json (new)
+  - packages/secure-exec/tests/e2e-docker/ssh2-tunnel/package.json (new)
+  - packages/secure-exec/tests/e2e-docker/ssh2-tunnel/src/index.js (new)
+  - packages/secure-exec/tests/utils/docker.ts (added getContainerInternalIp helper)
+  - packages/secure-exec/tests/e2e-docker.test.ts (added internalAddresses, REDIS_INTERNAL_HOST/PORT env injection)
+- **Learnings for future iterations:**
+  - SSH forwardOut() works through the sandbox net bridge without any additional fixes — it uses the same TCP stream as the SSH connection (direct-tcpip channel over existing SSH protocol)
+  - Docker containers on the default bridge network can reach each other by internal IP (from `docker inspect`), not by 127.0.0.1 host-mapped ports
+  - getContainerInternalIp() in docker.ts resolves a container's bridge IP via `docker inspect -f '{{.NetworkSettings.IPAddress}}'`
+  - Raw Redis PING protocol: send "PING\r\n" (inline format), response is "+PONG\r\n"
+  - For tunnel fixtures, use REDIS_INTERNAL_HOST/PORT (container bridge IP + internal port), not REDIS_HOST/PORT (host-mapped)
+---

scripts/ralph/prd.json

@@ -307,8 +307,8 @@
         "Tests pass"
       ],
       "priority": 17,
-      "passes": false,
-      "notes": "SSH tunneling (forwardOut/forwardIn) is commonly used for database access through bastion hosts. This exercises nested TCP streams through the sandbox's net bridge — a very different path than direct connections."
+      "passes": true,
+      "notes": "Completed. Fixture tunnels through SSH to Redis using forwardOut(). Test infra discovers container internal IPs on the Docker bridge via docker inspect. Sends raw Redis PING through the tunnel, verifies +PONG response. Host and sandbox produce identical output."
     },
     {
       "id": "US-018",