@celilo/e2e 0.7.14 → 0.7.16

package/src/docker-compose-generator.ts

@@ -1,6 +1,7 @@
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { stringify } from 'yaml';
+import { normalizeObservers, observerEnv, observerPlacement } from './observer';
 import { SIMULATOR_IPS } from './simulator-ips';
 import type { MachineSpec, NetworkConfig, TopologyPreset } from './types';
 import { ZONE_GATEWAYS } from './types';
@@ -216,7 +217,7 @@ export function generateSharedInfraYaml(): string {
     // `test123` still applies to any domain not listed.
     environment: {
       DDNS_PASSWORDS:
-        '{"iamtheinternet.org":"test123","celilo.computer":"test456","lunacycle.net":"test789"}',
+        '{"iamtheinternet.org":"test123","celilo.computer":"test456","example.net":"test789"}',
     },
     volumes: [
       './config/dns/knot-namecheap.conf:/config/knot.conf:ro',
@@ -227,7 +228,7 @@ export function generateSharedInfraYaml(): string {
       // namecheap-startup.sh for the full rationale).
       './config/dns/iamtheinternet.org.zone:/seed/iamtheinternet.org.zone:ro',
       './config/dns/celilo.computer.zone:/seed/celilo.computer.zone:ro',
-      './config/dns/lunacycle.net.zone:/seed/lunacycle.net.zone:ro',
+      './config/dns/example.net.zone:/seed/example.net.zone:ro',
       './config/dns/park-your-domain.com.zone:/seed/park-your-domain.com.zone:ro',
     ],
   });
@@ -504,6 +505,20 @@ export function generateTestComposeYaml(config: NetworkConfig, celiloRoot?: stri
     });
   }
 
+  // --- Observer vantages (passive spies; ISS-0117) ---
+  // Each is the SAME image at a different network location with a routing profile that
+  // mirrors a real device there — that routing profile is what makes it a faithful seat
+  // to assert from, rather than the all-VLAN management trap.
+  for (const spec of normalizeObservers(config.observers ?? [])) {
+    const p = observerPlacement(spec.vantage);
+    services[p.service] = baseService({
+      build: { context: '.', dockerfile: 'docker/Dockerfile.observer' },
+      networks: { [p.network]: { ipv4_address: p.ip } },
+      cap_add: ['NET_ADMIN'],
+      environment: observerEnv(p),
+    });
+  }
+
   const compose = { networks, volumes, services };
   return stringify(compose, { lineWidth: 120 });
 }
@@ -619,7 +634,7 @@ export function generateComposeYaml(config: NetworkConfig, celiloRoot = '..'): s
     // `test123` still applies to any domain not listed.
     environment: {
       DDNS_PASSWORDS:
-        '{"iamtheinternet.org":"test123","celilo.computer":"test456","lunacycle.net":"test789"}',
+        '{"iamtheinternet.org":"test123","celilo.computer":"test456","example.net":"test789"}',
     },
     volumes: [
       './config/dns/knot-namecheap.conf:/config/knot.conf:ro',
@@ -630,7 +645,7 @@ export function generateComposeYaml(config: NetworkConfig, celiloRoot = '..'): s
       // namecheap-startup.sh for the full rationale).
       './config/dns/iamtheinternet.org.zone:/seed/iamtheinternet.org.zone:ro',
       './config/dns/celilo.computer.zone:/seed/celilo.computer.zone:ro',
-      './config/dns/lunacycle.net.zone:/seed/lunacycle.net.zone:ro',
+      './config/dns/example.net.zone:/seed/example.net.zone:ro',
       './config/dns/park-your-domain.com.zone:/seed/park-your-domain.com.zone:ro',
     ],
   });

package/src/index.ts

@@ -37,6 +37,8 @@ export type {
   ExecResult,
   MachineSpec,
   Zone,
+  Vantage,
+  ObserverSpec,
   TopologyPreset,
   ProxyOptions,
   SocksProxyHandle,
@@ -44,7 +46,32 @@ export type {
   BrowserHandle,
   BrowserLauncher,
 } from './types';
-export { CeliloCommandError, ZONE_GATEWAYS, ZONE_SUBNETS } from './types';
+export {
+  CeliloCommandError,
+  greenwaveRouterIp,
+  internalNatIp,
+  internalResolverIp,
+  publicResolverIp,
+  ZONE_GATEWAYS,
+  ZONE_SUBNETS,
+} from './types';
+
+// Vantage-point network assertions (ISS-0117)
+export { VantageProbe, VantageAssertionError } from './vantage';
+export type {
+  ProbeTransport,
+  ResolveMethod,
+  ResolveResult,
+  HttpsResult,
+  CertInfo,
+  ResolutionInspection,
+  ExpectedZone,
+} from './vantage';
+export { createObserverTransport, vantageContainer, OBSERVER_PLACEMENTS } from './observer';
+export { classifyIp, isSegmentedZoneIp, isPublicLeakSafe } from './zone-classifier';
+export type { ZoneClass } from './zone-classifier';
+export { assertFrontedServicePositives, assertFrontedHostnames } from './vantage-helpers';
+export type { FrontedServiceExpectation } from './vantage-helpers';
 
 // Common fixtures
 export {

package/src/network-builder.ts

@@ -2,7 +2,7 @@ import { execSync } from 'node:child_process';
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { startNetwork } from './container-manager';
-import type { NetworkConfig, NetworkHandle, TopologyPreset } from './types';
+import type { NetworkConfig, NetworkHandle, TopologyPreset, Vantage } from './types';
 
 /**
  * If a mounted path looks like a celilo module (has scripts/package.json),
@@ -39,6 +39,7 @@ export class NetworkBuilder {
     secureMachines: [],
     internalMachines: [],
     dhcpClient: false,
+    observers: [],
     domain: 'iamtheinternet.org',
     ddnsPassword: 'test123',
     verifyRouting: process.env.VERIFY_ROUTING === '1',
@@ -104,6 +105,22 @@ export class NetworkBuilder {
     return this;
   }
 
+  /**
+   * Inject one or more observer vantages (ISS-0117) — passive spies carrying the probe
+   * toolbox, each placed at its vantage's network location with a routing profile that
+   * mirrors a real device there. Drive them via `createObserverTransport(handle)` +
+   * `VantageProbe`. `management` is not injectable (that vantage reuses the real
+   * management container).
+   *
+   *   network().dmz({ caddy: '10.0.10.10' }).observe('internalDevice', 'publicInternet')
+   */
+  observe(...vantages: Vantage[]): this {
+    for (const vantage of vantages) {
+      (this.config.observers ??= []).push({ vantage });
+    }
+    return this;
+  }
+
   domain(domain: string): this {
     this.config.domain = domain;
     return this;

package/src/observer.test.ts

@@ -0,0 +1,155 @@
+import { describe, expect, test } from 'bun:test';
+import {
+  createObserverTransport,
+  normalizeObservers,
+  OBSERVER_PLACEMENTS,
+  observerEnv,
+  vantageContainer,
+} from './observer';
+import type { ExecResult, NetworkHandle } from './types';
+import { ZONE_GATEWAYS } from './types';
+
+/** A NetworkHandle whose `exec` records calls and returns scripted results. */
+function fakeHandle(script: (container: string, cmd: string) => Partial<ExecResult>) {
+  const calls: { container: string; cmd: string }[] = [];
+  const exec = (container: string, cmd: string): Promise<ExecResult> => {
+    calls.push({ container, cmd });
+    return Promise.resolve({ stdout: '', stderr: '', exitCode: 0, ...script(container, cmd) });
+  };
+  return { handle: { exec } as unknown as NetworkHandle, calls };
+}
+
+describe('placement faithfulness (the load-bearing invariants)', () => {
+  test('internalDevice routes via the home router, NOT fw-main, and has no inter-zone routes', () => {
+    const p = OBSERVER_PLACEMENTS.internalDevice;
+    expect(p.network).toBe('internal');
+    expect(p.interZoneRoutes).toBe(false);
+    // The whole point: default route is the LAN's home router, never ZONE_GATEWAYS.internal
+    // (fw-main), which would hand it a path into the segmented zones.
+    expect(p.gateway).not.toBe(ZONE_GATEWAYS.internal);
+  });
+
+  test('no injectable observer carries inter-zone routes (only the management trap would)', () => {
+    for (const p of Object.values(OBSERVER_PLACEMENTS)) {
+      expect(p.interZoneRoutes).toBe(false);
+    }
+  });
+
+  test('segmented-zone observer IPs derive from their zone gateway (no pinned subnets)', () => {
+    expect(OBSERVER_PLACEMENTS.dmzSystem.gateway).toBe(ZONE_GATEWAYS.dmz);
+    expect(OBSERVER_PLACEMENTS.dmzSystem.ip).toBe(ZONE_GATEWAYS.dmz.replace(/\.\d+$/, '.240'));
+    expect(OBSERVER_PLACEMENTS.secureSystem.ip).toBe(ZONE_GATEWAYS.secure.replace(/\.\d+$/, '.240'));
+  });
+
+  test('publicInternet uses only the public resolver (never the internal split-horizon view)', () => {
+    expect(OBSERVER_PLACEMENTS.publicInternet.resolvers).toEqual(['100.100.0.1']);
+  });
+
+  test('observerEnv serializes the routing profile for the setup script', () => {
+    const env = observerEnv(OBSERVER_PLACEMENTS.internalDevice);
+    expect(env.OBSERVER_INTERZONE).toBe('0');
+    expect(env.OBSERVER_GATEWAY).toBe(OBSERVER_PLACEMENTS.internalDevice.gateway);
+    expect(env.OBSERVER_RESOLVERS).toContain('100.100.0.1');
+  });
+});
+
+describe('normalizeObservers + vantageContainer', () => {
+  test('dedupes and rejects management as an injectable observer', () => {
+    expect(normalizeObservers([{ vantage: 'internalDevice' }, { vantage: 'internalDevice' }])).toHaveLength(1);
+    expect(() => normalizeObservers([{ vantage: 'management' }])).toThrow(/management/);
+  });
+  test('management vantage maps to the real management container; others to observers', () => {
+    expect(vantageContainer('management')).toBe('management');
+    expect(vantageContainer('internalDevice')).toBe(OBSERVER_PLACEMENTS.internalDevice.service);
+  });
+});
+
+describe('observer transport — parsing + container targeting', () => {
+  test('resolve(system) parses getent first column and targets the right observer', async () => {
+    const { handle, calls } = fakeHandle((_c, cmd) =>
+      cmd.startsWith('getent') ? { stdout: '192.168.0.253  www.iamtheinternet.org' } : {},
+    );
+    const t = createObserverTransport(handle);
+    const r = await t.resolve({ from: 'internalDevice', name: 'www.iamtheinternet.org', method: 'system' });
+    expect(r.ips).toEqual(['192.168.0.253']);
+    expect(calls[0].container).toBe('observer-internal');
+  });
+
+  test('resolve(dns) with explicit server', async () => {
+    const { handle, calls } = fakeHandle((_c, cmd) => (cmd.includes('dig') ? { stdout: '10.0.10.10\n' } : {}));
+    const t = createObserverTransport(handle);
+    const r = await t.resolve({ from: 'dmzSystem', name: 'auth.x', method: 'dns', server: '192.168.0.10' });
+    expect(r.ips).toEqual(['10.0.10.10']);
+    expect(calls[0].cmd).toContain('@192.168.0.10');
+  });
+
+  test('resolve(hostfiles) parses /etc/hosts first column', async () => {
+    const { handle } = fakeHandle((_c, cmd) =>
+      cmd.startsWith('grep -F') ? { stdout: '10.0.10.10 auth.iamtheinternet.org' } : {},
+    );
+    const t = createObserverTransport(handle);
+    const r = await t.resolve({ from: 'dmzSystem', name: 'auth.iamtheinternet.org', method: 'hostfiles' });
+    expect(r.ips).toEqual(['10.0.10.10']);
+  });
+
+  test('tcpConnect maps the container exit code', async () => {
+    const { handle } = fakeHandle((_c, cmd) => ({ exitCode: cmd.includes('443') ? 0 : 1 }));
+    const t = createObserverTransport(handle);
+    expect((await t.tcpConnect({ from: 'internalDevice', host: '192.168.0.253', port: 443 })).connected).toBe(true);
+    expect((await t.tcpConnect({ from: 'internalDevice', host: '10.0.10.10', port: 22 })).connected).toBe(false);
+  });
+
+  test('httpsRequest parses cert (CN/issuer/SAN/selfSigned) + status', async () => {
+    const { handle } = fakeHandle((_c, cmd) => {
+      if (cmd.includes('openssl s_client')) {
+        return {
+          stdout:
+            'subject=CN = deathstar.iamtheinternet.org\n' +
+            'issuer=CN = Pebble Intermediate CA 1a2b3c\n' +
+            'X509v3 Subject Alternative Name:\n    DNS:deathstar.iamtheinternet.org\n',
+        };
+      }
+      if (cmd.includes('%{http_code}')) return { stdout: '200' };
+      return { stdout: 'Caddy reverse proxy is running' };
+    });
+    const t = createObserverTransport(handle);
+    const r = await t.httpsRequest({ from: 'publicInternet', url: 'https://deathstar.iamtheinternet.org' });
+    expect(r.status).toBe(200);
+    expect(r.cert.cn).toBe('deathstar.iamtheinternet.org');
+    expect(r.cert.issuer).toContain('Pebble');
+    expect(r.cert.subjectAltNames).toContain('deathstar.iamtheinternet.org');
+    expect(r.cert.selfSigned).toBe(false);
+  });
+
+  test('httpsRequest flags a self-signed cert (subject == issuer)', async () => {
+    const { handle } = fakeHandle((_c, cmd) =>
+      cmd.includes('openssl s_client')
+        ? { stdout: 'subject=CN = sketchy.local\nissuer=CN = sketchy.local\n' }
+        : cmd.includes('%{http_code}')
+          ? { stdout: '200' }
+          : {},
+    );
+    const t = createObserverTransport(handle);
+    const r = await t.httpsRequest({ from: 'internalDevice', url: 'https://sketchy.local' });
+    expect(r.cert.selfSigned).toBe(true);
+  });
+});
+
+describe('host-shell footgun guard', () => {
+  test('no command contains $(...) or backticks (would be host-evaluated through the wrap)', async () => {
+    const { handle, calls } = fakeHandle(() => ({ stdout: '200', exitCode: 0 }));
+    const t = createObserverTransport(handle);
+    await t.resolve({ from: 'internalDevice', name: 'www.x', method: 'system' });
+    await t.resolve({ from: 'internalDevice', name: 'www.x', method: 'dns', server: '192.168.0.10' });
+    await t.resolve({ from: 'internalDevice', name: 'www.x', method: 'hostfiles' });
+    await t.tcpConnect({ from: 'internalDevice', host: '10.0.10.10', port: 443 });
+    await t.ping({ from: 'internalDevice', target: '192.168.0.253' });
+    await t.httpsRequest({ from: 'internalDevice', url: 'https://www.x' });
+    await t.inspectResolution({ from: 'internalDevice', name: 'www.x' });
+    expect(calls.length).toBeGreaterThan(0);
+    for (const { cmd } of calls) {
+      expect(cmd).not.toContain('$(');
+      expect(cmd).not.toContain('`');
+    }
+  });
+});

package/src/observer.ts

@@ -0,0 +1,270 @@
+/**
+ * Observer vantages (ISS-0117 §D2/§D4) — the topology side of the vantage framework.
+ *
+ * An *observer* is a passive spy: a purpose-built container carrying all the probe
+ * tooling, injected at a named vantage's network location with a routing profile that
+ * mirrors a REAL device there. The point is faithfulness — a vantage's correctness is
+ * its routing table, not just which network it attaches to. The management box reaches
+ * a DMZ container IP directly only because management-routes.sh adds an explicit
+ * inter-zone route; a real LAN device has no such route, so it must go via the firewall
+ * natIp. An `internalDevice` observer reproduces the LAN device's routing exactly, which
+ * is how it catches the ISS-0101 / ISS-0111 "e2e-green/prod-broke" class.
+ *
+ * This file holds the single source of truth for each vantage's placement + routing
+ * profile (consumed by the compose generator), the vantage->container mapping, and the
+ * dockerExec-based ProbeTransport (the developer escape hatch the design retains; the
+ * typed probe-agent will wrap this same surface later).
+ *
+ * Commands sent through dockerExec deliberately avoid `$(...)`, backticks and unescaped
+ * `$` — those are evaluated by the HOST shell before reaching the container (the wrapping
+ * footgun CLAUDE.md documents). We rely on the container command's exit code (propagated
+ * by `docker compose exec`) instead of `echo $?`.
+ */
+
+import { type NetworkHandle, type ObserverSpec, type Vantage, ZONE_GATEWAYS } from './types';
+import type { CertInfo, ProbeTransport, ResolveMethod } from './vantage';
+
+export interface ObserverPlacement {
+  /** docker compose service name for this observer */
+  service: string;
+  /** docker network to attach to */
+  network: string;
+  /** the observer's own IP in that network */
+  ip: string;
+  /** default route (gateway) — the load-bearing faithfulness knob */
+  gateway: string;
+  /** add the management-style explicit inter-zone routes (only the `management` trap) */
+  interZoneRoutes: boolean;
+  /** nameservers written to /etc/resolv.conf, in order */
+  resolvers: string[];
+}
+
+// The internal LAN's home router (hands out DHCP option:router) and split-horizon
+// resolver. Literals here match the values the compose generator + dnsmasq already use;
+// they are roles, not pins repeated into tests. ZONE_GATEWAYS.internal (.254) is fw-main
+// — the firewall to the segmented zones — NOT the LAN's default route, which is the home
+// router below. A faithful internalDevice routes its default via the home router and has
+// NO route to the segmented zones, so a dmz/app/secure container IP is unreachable.
+const HOME_ROUTER = '192.168.0.1';
+const INTERNAL_RESOLVER = '192.168.0.10';
+const PUBLIC_RESOLVER = '100.100.0.1';
+const INTERNET_GATEWAY = '100.64.0.1'; // fw-ext, on internet-external
+
+/** Derive an observer host IP in a zone from its gateway (no new literal subnets). */
+function observerIpInZone(zone: 'dmz' | 'app' | 'secure'): string {
+  return ZONE_GATEWAYS[zone].replace(/\.\d+$/, '.240');
+}
+
+/**
+ * Placement + routing profile per injectable vantage. `management` is intentionally
+ * absent — that vantage reuses the real `management` container (see vantageContainer),
+ * so the trap is demonstrated with the actual all-VLAN box, not a copy.
+ */
+export const OBSERVER_PLACEMENTS: Record<Exclude<Vantage, 'management'>, ObserverPlacement> = {
+  internalDevice: {
+    service: 'observer-internal',
+    network: 'internal',
+    ip: '192.168.0.211', // a LAN host (dhcp range is .200-.220; dhcp-client is .210)
+    gateway: HOME_ROUTER,
+    interZoneRoutes: false,
+    // Identical DNS to the management box on purpose: the only difference vs management
+    // is the routing profile, so any reachability gap is provably routing — the bug.
+    resolvers: [INTERNAL_RESOLVER, PUBLIC_RESOLVER],
+  },
+  dmzSystem: {
+    service: 'observer-dmz',
+    network: 'dmz',
+    ip: observerIpInZone('dmz'),
+    gateway: ZONE_GATEWAYS.dmz,
+    interZoneRoutes: false,
+    resolvers: [INTERNAL_RESOLVER, PUBLIC_RESOLVER],
+  },
+  appSystem: {
+    service: 'observer-app',
+    network: 'app',
+    ip: observerIpInZone('app'),
+    gateway: ZONE_GATEWAYS.app,
+    interZoneRoutes: false,
+    resolvers: [INTERNAL_RESOLVER, PUBLIC_RESOLVER],
+  },
+  secureSystem: {
+    service: 'observer-secure',
+    network: 'secure',
+    ip: observerIpInZone('secure'),
+    gateway: ZONE_GATEWAYS.secure,
+    interZoneRoutes: false,
+    resolvers: [INTERNAL_RESOLVER, PUBLIC_RESOLVER],
+  },
+  publicInternet: {
+    service: 'observer-public',
+    network: 'internet-external',
+    ip: '100.64.0.240',
+    gateway: INTERNET_GATEWAY,
+    interZoneRoutes: false,
+    // Outside the firewall: only the public resolver, never the internal split-horizon view.
+    resolvers: [PUBLIC_RESOLVER],
+  },
+};
+
+/** The placement for an injectable vantage; throws for `management` (not injectable). */
+export function observerPlacement(vantage: Vantage): ObserverPlacement {
+  if (vantage === 'management') {
+    throw new Error('management has no observer placement — it reuses the real management container.');
+  }
+  return OBSERVER_PLACEMENTS[vantage];
+}
+
+/** The container a vantage probes from. `management` reuses the real management box. */
+export function vantageContainer(vantage: Vantage): string {
+  if (vantage === 'management') return 'management';
+  return OBSERVER_PLACEMENTS[vantage].service;
+}
+
+/** Environment a generated observer service needs for its routing-profile setup script. */
+export function observerEnv(placement: ObserverPlacement): Record<string, string> {
+  return {
+    OBSERVER_GATEWAY: placement.gateway,
+    OBSERVER_INTERZONE: placement.interZoneRoutes ? '1' : '0',
+    OBSERVER_RESOLVERS: placement.resolvers.join(' '),
+  };
+}
+
+/** Dedupe + validate a list of observer specs (a vantage can't be injected twice). */
+export function normalizeObservers(observers: ObserverSpec[]): ObserverSpec[] {
+  const seen = new Set<Vantage>();
+  const out: ObserverSpec[] = [];
+  for (const spec of observers) {
+    if (spec.vantage === 'management') {
+      throw new Error(
+        'management is not an injectable observer — that vantage reuses the real management container.',
+      );
+    }
+    if (seen.has(spec.vantage)) continue;
+    seen.add(spec.vantage);
+    out.push(spec);
+  }
+  return out;
+}
+
+// --- dockerExec-based ProbeTransport (escape hatch; substitution-free commands) ---
+
+const IPV4 = /^\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}$/;
+
+/**
+ * The first whitespace token of each line, kept if it's an IPv4. Works for all three
+ * resolve methods without shell-side column extraction (which would need `$1`/awk — a
+ * host-shell-expansion footgun): `dig +short` lines ARE the IP; `getent hosts` and
+ * `/etc/hosts` lines are "IP  name…", so token[0] is the IP either way.
+ */
+function firstColumnIps(stdout: string): string[] {
+  return stdout
+    .split('\n')
+    .map((l) => l.trim().split(/\s+/)[0] ?? '')
+    .filter((tok) => IPV4.test(tok));
+}
+
+function hostPort(url: string): { host: string; port: number } {
+  const u = new URL(url);
+  return { host: u.hostname, port: u.port ? Number(u.port) : u.protocol === 'https:' ? 443 : 80 };
+}
+
+function parseCert(opensslOut: string): CertInfo {
+  const subjectLine = opensslOut.match(/^subject=(.*)$/m)?.[1]?.trim() ?? '';
+  const issuerLine = opensslOut.match(/^issuer=(.*)$/m)?.[1]?.trim() ?? '';
+  const cn = subjectLine.match(/CN\s*=\s*([^,/]+)/)?.[1]?.trim() ?? '';
+  const issuerCn = issuerLine.match(/CN\s*=\s*([^,/]+)/)?.[1]?.trim() ?? issuerLine;
+  const sanLine = opensslOut.match(/DNS:[^\n]*/)?.[0] ?? '';
+  const subjectAltNames = sanLine
+    .split(',')
+    .map((s) => s.replace(/.*DNS:/, '').trim())
+    .filter(Boolean);
+  return {
+    cn,
+    issuer: issuerCn,
+    subjectAltNames,
+    // Pebble's leaf issuer differs from the leaf subject; equal subject==issuer ⇒ self-signed.
+    selfSigned: subjectLine !== '' && subjectLine === issuerLine,
+  };
+}
+
+/**
+ * A ProbeTransport that runs each verb's probe inside the vantage's observer container
+ * via `handle.exec`. Returns typed results; raw dockerExec stays available on `handle`.
+ */
+export function createObserverTransport(handle: NetworkHandle): ProbeTransport {
+  return {
+    async resolve(opts) {
+      const c = vantageContainer(opts.from);
+      const cmd = resolveCommand(opts.name, opts.method, opts.server);
+      const res = await handle.exec(c, cmd, 15_000);
+      return { ips: firstColumnIps(res.stdout) };
+    },
+
+    async tcpConnect(opts) {
+      const c = vantageContainer(opts.from);
+      // bash's /dev/tcp builtin, not `nc`: the management box (a valid vantage) ships no
+      // netcat, whereas /dev/tcp works on every vantage. `timeout` bounds a hung connect.
+      const res = await handle.exec(
+        c,
+        `timeout 4 bash -c 'exec 3<>/dev/tcp/${opts.host}/${opts.port}'`,
+        8_000,
+      );
+      return { connected: res.exitCode === 0, detail: res.exitCode === 0 ? undefined : 'connect failed/timed out' };
+    },
+
+    async ping(opts) {
+      const c = vantageContainer(opts.from);
+      const res = await handle.exec(c, `ping -c 1 -W 2 ${opts.target}`, 6_000);
+      return { alive: res.exitCode === 0 };
+    },
+
+    async httpsRequest(opts) {
+      const c = vantageContainer(opts.from);
+      const { host, port } = hostPort(opts.url);
+      const certRes = await handle.exec(
+        c,
+        `echo | openssl s_client -connect ${host}:${port} -servername ${host} 2>/dev/null | ` +
+          'openssl x509 -noout -subject -issuer -ext subjectAltName',
+        10_000,
+      );
+      // -k gathers the status even for an untrusted chain; the cert is reported truthfully
+      // above so the verb layer asserts provenance separately (this is fact-gathering, not
+      // validation-skipping — the no-insecure rule is enforced by the verb, not relaxed here).
+      const statusRes = await handle.exec(
+        c,
+        `curl -sk -o /dev/null -w '%{http_code}' --max-time 8 ${opts.url}`,
+        10_000,
+      );
+      const bodyRes = await handle.exec(c, `curl -sk --max-time 8 ${opts.url}`, 10_000);
+      return {
+        status: Number.parseInt(statusRes.stdout.trim(), 10) || 0,
+        body: bodyRes.stdout,
+        cert: parseCert(certRes.stdout),
+      };
+    },
+
+    async inspectResolution(opts) {
+      const c = vantageContainer(opts.from);
+      const resolv = await handle.exec(c, 'cat /etc/resolv.conf', 5_000);
+      const hosts = await handle.exec(c, `grep -F ${opts.name} /etc/hosts`, 5_000);
+      return {
+        resolvConf: resolv.stdout.trim(),
+        hostsLines: hosts.stdout.split('\n').map((l) => l.trim()).filter(Boolean),
+      };
+    },
+  };
+}
+
+function resolveCommand(name: string, method: ResolveMethod, server?: string): string {
+  switch (method) {
+    case 'dns':
+      // DNS only (ignores /etc/hosts); optionally a specific resolver.
+      return `dig +short A ${name}${server ? ` @${server}` : ''}`;
+    case 'hostfiles':
+      // The /etc/hosts layer only (the host-pin path — ISS-0095). Raw; parsed host-side.
+      return `grep -F ${name} /etc/hosts`;
+    default:
+      // system: the real stack — nsswitch consults files AND dns. getent prints "IP name...".
+      return `getent hosts ${name}`;
+  }
+}

package/src/shared-infra.ts

@@ -12,7 +12,7 @@
 
 import { execSync } from 'node:child_process';
 import { join } from 'node:path';
-import { writeFileSync } from 'node:fs';
+import { copyFileSync, existsSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { generateSharedInfraYaml, SHARED_PROJECT_NAME, SHARED_NETWORKS } from './docker-compose-generator';
 import { ensureRegistryServerBundle } from './registry-bundle';
 
@@ -146,6 +146,23 @@ export async function ensureSharedInfra(): Promise<void> {
   const yaml = generateSharedInfraYaml();
   writeFileSync(join(e2eDir, SHARED_COMPOSE_FILE), yaml);
 
+  // Seed the live DNS zone files from their templates BEFORE the compose
+  // mounts them. config/dns/{iamtheinternet.org,example.net}.zone are
+  // gitignored runtime state (scrubDnsZones rewrites them per-test); on a
+  // fresh checkout they don't exist yet, and a Docker bind-mount of a missing
+  // host path silently creates an empty DIRECTORY — so Knot serves no zone and
+  // DNS convergence times out. Seeding here makes the bind-mount targets real
+  // files, so shared infra bootstraps from a clean checkout (e.g. CI builder).
+  for (const zone of ['iamtheinternet.org', 'example.net']) {
+    const tpl = join(e2eDir, 'config', 'dns', 'templates', `${zone}.zone`);
+    const live = join(e2eDir, 'config', 'dns', `${zone}.zone`);
+    // Remove an empty dir left by a prior bind-mount on a missing path.
+    if (existsSync(live) && statSync(live).isDirectory()) {
+      rmSync(live, { recursive: true, force: true });
+    }
+    copyFileSync(tpl, live);
+  }
+
   // Build and start
   console.log('[progress:start] building shared infrastructure images | shared images built');
   run(`docker compose -f ${SHARED_COMPOSE_FILE} -p ${SHARED_PROJECT_NAME} build`,

package/src/types.ts

@@ -1,5 +1,25 @@
 export type Zone = 'dmz' | 'app' | 'secure' | 'internal';
 
+/**
+ * Where a network assertion is made FROM — named by the box's network location
+ * (ISS-0117 §D4). A vantage is realized in the topology by an `observer` container
+ * (passive spy with all probe tooling) placed at that location with a routing profile
+ * that mirrors a real device there. `from` is always explicit — there is no default
+ * vantage, so adding one can't silently change an existing test.
+ */
+export type Vantage =
+  | 'internalDevice' // unmanaged device on the internal/Home LAN; NO route into dmz/app/secure (the real end-user)
+  | 'dmzSystem'
+  | 'appSystem'
+  | 'secureSystem'
+  | 'publicInternet' // outside the firewall — what the real internet sees
+  | 'management'; // celilo-mgmt box; all-VLAN routes (the trap — explicit, rare)
+
+/** A request to inject an observer at a vantage (passive spy with controlled routing). */
+export interface ObserverSpec {
+  vantage: Vantage;
+}
+
 export interface MachineSpec {
   name: string;
   ip: string;
@@ -25,6 +45,13 @@ export interface NetworkConfig {
   managementVolumes: string[];
   /** Include a DHCP client container on the internal network */
   dhcpClient: boolean;
+  /**
+   * Observer vantages to inject into the topology. Each becomes an `observer-*`
+   * container — a passive spy carrying the probe tooling, placed at the named
+   * vantage's network location with a routing profile that mirrors a real device
+   * there (ISS-0117). Drive them via the VantageProbe transport.
+   */
+  observers?: ObserverSpec[];
   /**
    * Absolute path to the Celilo project root (the directory containing apps/celilo/).
    * Mounted into the management container at /celilo so the CLI is available.
@@ -330,3 +357,34 @@ export const ZONE_SUBNETS: Record<Zone, string> = {
   secure: '10.0.30.0/24',
   internal: '192.168.0.0/24',
 };
+
+/**
+ * The firewall's internal-side DNAT ingress (the natIp) in the e2e topology — the role by
+ * which an internal device reaches a service that lives in a segmented zone. Single source
+ * of truth: `deployFirewall` uses it as its default and tests assert against it, so the
+ * asserted natIp is by construction the one that was deployed. Reference this instead of
+ * hardcoding the address in a test.
+ */
+export function internalNatIp(): string {
+  return '192.168.0.253';
+}
+
+/**
+ * The internal network's internet-facing gateway router (the greenwave / fw-isp sim) — the
+ * default route for internal devices toward the internet. Distinct from
+ * `ZONE_GATEWAYS.internal` (fw-main), which is the firewall to the segmented zones. Reference
+ * this instead of hardcoding the address in a test.
+ */
+export function greenwaveRouterIp(): string {
+  return '192.168.0.1';
+}
+
+/** The internal split-horizon DNS resolver (dns-int) in the e2e topology. */
+export function internalResolverIp(): string {
+  return '192.168.0.10';
+}
+
+/** The public upstream recursive resolver (the comcast-resolver sim). */
+export function publicResolverIp(): string {
+  return '100.100.0.1';
+}