@intentius/chant-lexicon-aws 0.33.1 → 0.34.0

package/src/defaults.ts

@@ -0,0 +1,97 @@
+/**
+ * Which resources the provider created, rather than anyone's infrastructure code.
+ *
+ * Every account arrives with resources nobody wrote: a default VPC and its
+ * subnets, a default security group per VPC, a main route table, AWS-managed
+ * KMS keys and IAM policies. They are yours to account for and were never
+ * yours to declare, and until now chant recorded them looking exactly like
+ * everything else.
+ *
+ * That matters wherever a question is about what you built. Asked which
+ * security groups were unused, agents split three ways on the same correct set
+ * of four — one excluded the three VPC defaults as "not real cleanup
+ * candidates" and answered one, another counted something extra and answered
+ * five. The answers that were accepted all did the same thing: listed all four
+ * and said which were defaults. They could only do that by recognising them,
+ * and chant gave them nothing to recognise them by.
+ *
+ * This records a fact and stops. `providerDefault: true` says the provider
+ * created this; it does not say the resource is unused, safe to ignore, or
+ * exempt from anything. Deciding that here would put a conclusion in an
+ * observation — the mistake `liveInternetFacing` made and #1271 undid — and it
+ * would be wrong in this very case, since the accepted answers count defaults
+ * as unused.
+ *
+ * Almost none of this is chant's judgement. AWS marks these itself, on the same
+ * payloads chant already reads; the fields were simply being dropped. The one
+ * derivation is the security group, and it is safe because `default` is a
+ * reserved group name — AWS rejects it on create, so a group called `default`
+ * is that VPC's default group.
+ */
+
+import type { ResourceMetadata } from "@intentius/chant/lexicon";
+
+type Attrs = Record<string, unknown>;
+
+/**
+ * Per kind, the provider's own marker. Extending this is the way to widen.
+ *
+ * Each predicate reads a field AWS already returns, so this is a passthrough
+ * rather than a heuristic — a resource is a default because the provider says
+ * so, not because it looks like one.
+ */
+const PROVIDER_DEFAULT: Record<string, (attrs: Attrs) => boolean> = {
+  "AWS::EC2::VPC": (a) => a.IsDefault === true,
+  "AWS::EC2::Subnet": (a) => a.DefaultForAz === true,
+  "AWS::EC2::NetworkAcl": (a) => a.IsDefault === true,
+  // `default` is a reserved group name: AWS refuses it on create, so a group
+  // carrying it is the one AWS made with the VPC.
+  "AWS::EC2::SecurityGroup": (a) => a.GroupName === "default",
+  // The main route table is the one a subnet falls back to when it has no
+  // explicit association — created with the VPC and not by anyone.
+  "AWS::EC2::RouteTable": (a) =>
+    Array.isArray(a.Associations) &&
+    a.Associations.some((x) => (x as Attrs | null)?.Main === true),
+  "AWS::KMS::Key": (a) => a.KeyManager === "AWS",
+  "AWS::IAM::ManagedPolicy": (a) =>
+    typeof a.Arn === "string" && a.Arn.startsWith("arn:aws:iam::aws:policy/"),
+  "AWS::IAM::Policy": (a) =>
+    typeof a.Arn === "string" && a.Arn.startsWith("arn:aws:iam::aws:policy/"),
+};
+
+/** True when this lexicon can tell whether the kind is a provider default. */
+export function canDetectDefault(kind: string): boolean {
+  return kind in PROVIDER_DEFAULT;
+}
+
+/** The kinds whose provider-default status this lexicon can report. */
+export const DEFAULT_AWARE_KINDS: string[] = Object.keys(PROVIDER_DEFAULT);
+
+/**
+ * Mark the resources the provider created.
+ *
+ * Only ever sets the attribute to `true`, and only for kinds with a known
+ * marker: absent means "not a default, or chant cannot tell", and those are
+ * genuinely different from each other in a way a blanket `false` would hide.
+ */
+export function stampProviderDefaults(
+  resources: Record<string, ResourceMetadata>,
+): Record<string, ResourceMetadata> {
+  const stamped: Record<string, ResourceMetadata> = {};
+  for (const [name, meta] of Object.entries(resources)) {
+    const test = PROVIDER_DEFAULT[meta.type];
+    const attrs = (meta.attributes ?? {}) as Attrs;
+    let isDefault = false;
+    try {
+      isDefault = test ? test(attrs) : false;
+    } catch {
+      // A malformed payload is not a default; it is a payload chant could not
+      // read, and the rest of the observation is still good.
+      isDefault = false;
+    }
+    stamped[name] = isDefault
+      ? { ...meta, attributes: { ...attrs, providerDefault: true } }
+      : meta;
+  }
+  return stamped;
+}

package/src/dependencies.test.ts

@@ -0,0 +1,208 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+
+// Every AWS interaction is a mocked `spawn` — the reader's only edge is the
+// runtime adapter, and nothing here constructs a client or reaches a network.
+const spawnMock = vi.fn();
+vi.mock("@intentius/chant/runtime-adapter", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("@intentius/chant/runtime-adapter")>();
+  return { ...actual, getRuntime: () => ({ ...actual.getRuntime(), spawn: spawnMock }) };
+});
+
+const { toIngressRules, observeAwsDependencies } = await import("./dependencies");
+
+const ok = (body: unknown) => ({ stdout: JSON.stringify(body), stderr: "", exitCode: 0 });
+
+/** Route the mock by the AWS subcommand, so ordering is not load-bearing. */
+function respond(handlers: Record<string, unknown>) {
+  spawnMock.mockImplementation((...args: unknown[]) => {
+    const argv = (args[0] ?? []) as string[];
+    const at = argv.indexOf("aws");
+    const key = argv.slice(at + 1, at + 3).join(" ");
+    const body = handlers[key];
+    return Promise.resolve(body ? ok(body) : { stdout: "", stderr: "not mocked: " + key, exitCode: 255 });
+  });
+}
+
+// #1276 — the two AWS surfaces disagree about the same concept. A template's
+// SecurityGroupIngress carries CidrIp flat; describe-security-groups nests
+// sources under IpRanges[]/Ipv6Ranges[]/UserIdGroupPairs[], and one permission
+// can hold several. Handing the describe shape to the fold unchanged renders
+// every source as `?`, which matches no CIDR query and narrows the answer.
+describe("toIngressRules (#1276)", () => {
+  it("flattens an IPv4 range into the flat rule the fold reads", () => {
+    expect(
+      toIngressRules([{ IpProtocol: "tcp", FromPort: 22, ToPort: 22, IpRanges: [{ CidrIp: "0.0.0.0/0" }] }]),
+    ).toEqual([{ IpProtocol: "tcp", FromPort: 22, ToPort: 22, CidrIp: "0.0.0.0/0" }]);
+  });
+
+  it("emits one rule per source, because that is what the flat shape means", () => {
+    const rules = toIngressRules([
+      {
+        IpProtocol: "tcp",
+        FromPort: 443,
+        ToPort: 443,
+        IpRanges: [{ CidrIp: "10.0.0.0/8" }, { CidrIp: "192.168.0.0/16" }],
+        UserIdGroupPairs: [{ GroupId: "sg-peer" }],
+      },
+    ]);
+    expect(rules).toHaveLength(3);
+    expect(rules.map((r) => r.CidrIp ?? r.SourceSecurityGroupId)).toEqual([
+      "10.0.0.0/8",
+      "192.168.0.0/16",
+      "sg-peer",
+    ]);
+  });
+
+  it("carries IPv6 sources through their own key", () => {
+    expect(toIngressRules([{ IpProtocol: "tcp", Ipv6Ranges: [{ CidrIpv6: "::/0" }] }])).toEqual([
+      { IpProtocol: "tcp", CidrIpv6: "::/0" },
+    ]);
+  });
+
+  it("an all-protocols rule keeps the -1 the fold expects, and omits absent ports", () => {
+    // FromPort absent is "all ports" to normalizeIngress; emitting FromPort:
+    // undefined would render as a port range rather than `all`.
+    expect(toIngressRules([{ IpRanges: [{ CidrIp: "0.0.0.0/0" }] }])).toEqual([
+      { IpProtocol: "-1", CidrIp: "0.0.0.0/0" },
+    ]);
+  });
+
+  it("a permission with no source contributes nothing", () => {
+    expect(toIngressRules([{ IpProtocol: "tcp", FromPort: 22, ToPort: 22 }])).toEqual([]);
+  });
+});
+
+
+// #1276 — the case the benchmark estate deliberately cannot exercise, because
+// it declares every security group. The fix matters precisely where an instance
+// is guarded by a group nobody declared, so it is proven here rather than by
+// changing a scenario a published comparison depends on.
+describe("undeclared security groups (#1276)", () => {
+  beforeEach(() => spawnMock.mockReset());
+
+  const observedInstanceOnly = {
+    webServer: { type: "AWS::EC2::Instance", status: "CREATE_COMPLETE", physicalId: "i-1" },
+  };
+
+  it("reports a security group the estate never declared, with its rules", async () => {
+    respond({
+      "ec2 describe-instances": {
+        Reservations: [
+          {
+            Instances: [
+              { InstanceId: "i-1", SubnetId: "subnet-1", VpcId: "vpc-1", SecurityGroups: [{ GroupId: "sg-shared" }] },
+            ],
+          },
+        ],
+      },
+      "ec2 describe-route-tables": { RouteTables: [] },
+      "ec2 describe-security-groups": {
+        SecurityGroups: [
+          {
+            GroupId: "sg-shared",
+            VpcId: "vpc-1",
+            IpPermissions: [
+              { IpProtocol: "tcp", FromPort: 22, ToPort: 22, IpRanges: [{ CidrIp: "0.0.0.0/0" }] },
+            ],
+          },
+        ],
+      },
+    });
+
+    const { resources, edges } = await observeAwsDependencies({ observed: observedInstanceOnly });
+
+    // The group is a node now, so the fold can read its rules at all.
+    expect(resources["sg-shared"]).toMatchObject({
+      type: "AWS::EC2::SecurityGroup",
+      physicalId: "sg-shared",
+      referencedBy: ["webServer"],
+    });
+    // In the flat shape the fold reads — not the nested describe shape, which
+    // would render every source as `?` and match no CIDR query.
+    expect(resources["sg-shared"].attributes?.SecurityGroupIngress).toEqual([
+      { IpProtocol: "tcp", FromPort: 22, ToPort: 22, CidrIp: "0.0.0.0/0" },
+    ]);
+    expect(edges).toContainEqual({ from: "webServer", to: "sg-shared", kind: "ref", viaAttr: "SecurityGroupIds" });
+  });
+
+  it("does not report a group the estate already declares", async () => {
+    respond({
+      "ec2 describe-instances": {
+        Reservations: [
+          { Instances: [{ InstanceId: "i-1", SubnetId: "subnet-1", SecurityGroups: [{ GroupId: "sg-mine" }] }] },
+        ],
+      },
+      "ec2 describe-route-tables": { RouteTables: [] },
+    });
+
+    const { resources } = await observeAwsDependencies({
+      observed: {
+        ...observedInstanceOnly,
+        webSg: { type: "AWS::EC2::SecurityGroup", status: "CREATE_COMPLETE", physicalId: "sg-mine" },
+      },
+    });
+
+    // Declared resources are the managed observation's job. Reporting one here
+    // too would double it as both managed and dependency.
+    expect(resources["sg-mine"]).toBeUndefined();
+  });
+
+  it("follows a launch template to the groups it attaches", async () => {
+    respond({
+      "ec2 describe-instances": {
+        Reservations: [
+          {
+            Instances: [
+              {
+                InstanceId: "i-1",
+                SubnetId: "subnet-1",
+                SecurityGroups: [],
+                LaunchTemplate: { LaunchTemplateId: "lt-1" },
+              },
+            ],
+          },
+        ],
+      },
+      "ec2 describe-route-tables": { RouteTables: [] },
+      "ec2 describe-launch-template-versions": {
+        LaunchTemplateVersions: [{ LaunchTemplateData: { SecurityGroupIds: ["sg-via-lt"] } }],
+      },
+      "ec2 describe-security-groups": {
+        SecurityGroups: [
+          {
+            GroupId: "sg-via-lt",
+            IpPermissions: [
+              { IpProtocol: "tcp", FromPort: 22, ToPort: 22, IpRanges: [{ CidrIp: "0.0.0.0/0" }] },
+            ],
+          },
+        ],
+      },
+    });
+
+    const { resources, edges } = await observeAwsDependencies({ observed: observedInstanceOnly });
+
+    // The indirect hop — the one a flat describe-instances sweep misses, and
+    // the reason effectiveIngress is a fold rather than a passthrough.
+    expect(resources["lt-1"]).toMatchObject({ type: "AWS::EC2::LaunchTemplate" });
+    expect(resources["sg-via-lt"]).toMatchObject({ type: "AWS::EC2::SecurityGroup" });
+    expect(edges).toContainEqual({ from: "webServer", to: "lt-1", kind: "ref", viaAttr: "LaunchTemplateId" });
+    expect(edges).toContainEqual({ from: "lt-1", to: "sg-via-lt", kind: "ref", viaAttr: "SecurityGroupIds" });
+  });
+
+  it("an instance with no internet route still reports its groups", async () => {
+    // effectiveIngress is asked about instances that are not internet-facing
+    // too; guarding must not be conditional on routing.
+    respond({
+      "ec2 describe-instances": {
+        Reservations: [
+          { Instances: [{ InstanceId: "i-1", SubnetId: "subnet-private", SecurityGroups: [{ GroupId: "sg-shared" }] }] },
+        ],
+      },
+      "ec2 describe-route-tables": { RouteTables: [] },
+      "ec2 describe-security-groups": { SecurityGroups: [{ GroupId: "sg-shared", IpPermissions: [] }] },
+    });
+
+    const { resources } = await observeAwsDependencies({ observed: observedInstanceOnly });
+    expect(resources["sg-shared"]).toBeDefined();
+  });
+});

package/src/dependencies.ts

@@ -0,0 +1,323 @@
+/**
+ * What an AWS estate depends on but does not declare (#1273).
+ *
+ * `describeResources` is scoped to the stack. An instance placed in the
+ * account's default VPC routes through a route table nobody declared, so that
+ * table is never observed, never a node, and no fold can traverse to it. The
+ * answer used to be computed inside the lexicon and injected as an attribute —
+ * which is a conclusion no snapshot can record enough to recompute.
+ *
+ * This reports the resources instead, so the one graph fold derives the answer.
+ *
+ * The closure is bounded: start from the observed instances, follow the
+ * reference chain the catalog declares as meaningful — subnet, then route
+ * table, then gateway — and stop. Anything not reached from a declared resource
+ * along a declared reference is not a dependency, it is just the account.
+ */
+
+import { applyAwsEndpointArgv } from "./components/cloud-executor";
+import type { DependencyObservation, ResourceMetadata, IREdge } from "@intentius/chant/lexicon";
+
+/** Cloud-shaped ids are stable across a redeploy and unique per account. */
+const nodeId = (physicalId: string): string => physicalId;
+
+/** One ingress permission as `describe-security-groups` returns it. */
+interface RawIpPermission {
+  IpProtocol?: string;
+  FromPort?: number;
+  ToPort?: number;
+  IpRanges?: Array<{ CidrIp?: string }>;
+  Ipv6Ranges?: Array<{ CidrIpv6?: string }>;
+  UserIdGroupPairs?: Array<{ GroupId?: string }>;
+}
+
+/**
+ * Flatten `IpPermissions` into the CloudFormation-shaped rules the fold reads.
+ *
+ * The two AWS surfaces disagree about the same concept: a template's
+ * `SecurityGroupIngress` carries `CidrIp` flat on the rule, while
+ * `describe-security-groups` nests sources under `IpRanges[]`, `Ipv6Ranges[]`
+ * and `UserIdGroupPairs[]`, and one permission can hold several. Handing the
+ * describe shape to the fold unchanged yields a rule with no recognisable
+ * source, which `normalizeIngress` renders as `?` — an ingress rule that
+ * matches no CIDR query and quietly narrows the answer.
+ *
+ * One rule per source, because that is what the flat shape means.
+ */
+export function toIngressRules(permissions: RawIpPermission[]): Array<Record<string, unknown>> {
+  const rules: Array<Record<string, unknown>> = [];
+  for (const permission of permissions) {
+    const base = {
+      IpProtocol: permission.IpProtocol ?? "-1",
+      ...(permission.FromPort != null ? { FromPort: permission.FromPort } : {}),
+      ...(permission.ToPort != null ? { ToPort: permission.ToPort } : {}),
+    };
+    for (const range of permission.IpRanges ?? []) {
+      if (range.CidrIp) rules.push({ ...base, CidrIp: range.CidrIp });
+    }
+    for (const range of permission.Ipv6Ranges ?? []) {
+      if (range.CidrIpv6) rules.push({ ...base, CidrIpv6: range.CidrIpv6 });
+    }
+    for (const pair of permission.UserIdGroupPairs ?? []) {
+      if (pair.GroupId) rules.push({ ...base, SourceSecurityGroupId: pair.GroupId });
+    }
+  }
+  return rules;
+}
+
+interface RawRouteTable {
+  RouteTableId?: string;
+  VpcId?: string;
+  Routes?: Array<{ GatewayId?: string; DestinationCidrBlock?: string }>;
+  Associations?: Array<{ SubnetId?: string; Main?: boolean }>;
+}
+
+/**
+ * Read the routing an observed estate depends on.
+ *
+ * Only the tables that actually serve an observed instance are reported: one
+ * reached by an explicit subnet association, or the VPC's main table standing in
+ * for a subnet with none. A route table serving nothing chant deployed is not a
+ * dependency of this estate.
+ */
+export async function observeAwsDependencies(options: {
+  observed: Record<string, ResourceMetadata>;
+  region?: string;
+}): Promise<DependencyObservation> {
+  const { getRuntime } = await import("@intentius/chant/runtime-adapter");
+  const rt = getRuntime();
+  const regionArgs = options.region ? ["--region", options.region] : [];
+  const run = (args: string[]) =>
+    rt.spawn(applyAwsEndpointArgv(["aws", ...args, ...regionArgs, "--output", "json"], process.env.AWS_ENDPOINT_URL));
+
+  const resources: Record<string, ResourceMetadata> = {};
+  const edges: IREdge[] = [];
+
+  // Roots: the instances this estate manages, and where each one sits. Placement
+  // comes from the live API rather than the template, because the declared side
+  // may only carry a parameter reference to a subnet it never modelled.
+  const instances = Object.entries(options.observed).filter(
+    ([, meta]) => meta.type === "AWS::EC2::Instance" && meta.physicalId,
+  );
+  if (instances.length === 0) return { resources: {}, edges: [] };
+
+  try {
+    const described = await run([
+      "ec2",
+      "describe-instances",
+      "--instance-ids",
+      ...instances.map(([, meta]) => meta.physicalId as string),
+    ]);
+    if (described.exitCode !== 0) return { resources: {}, edges: [] };
+
+    const placement = new Map<
+      string,
+      { subnetId?: string; vpcId?: string; securityGroupIds: string[]; launchTemplateId?: string }
+    >();
+    for (const reservation of (JSON.parse(described.stdout).Reservations ?? []) as Array<{
+      Instances?: Array<{
+        InstanceId: string;
+        SubnetId?: string;
+        VpcId?: string;
+        SecurityGroups?: Array<{ GroupId?: string }>;
+        LaunchTemplate?: { LaunchTemplateId?: string };
+      }>;
+    }>) {
+      for (const instance of reservation.Instances ?? []) {
+        placement.set(instance.InstanceId, {
+          subnetId: instance.SubnetId,
+          vpcId: instance.VpcId,
+          securityGroupIds: (instance.SecurityGroups ?? [])
+            .map((g) => g.GroupId)
+            .filter((id): id is string => typeof id === "string"),
+          ...(instance.LaunchTemplate?.LaunchTemplateId
+            ? { launchTemplateId: instance.LaunchTemplate.LaunchTemplateId }
+            : {}),
+        });
+      }
+    }
+
+    const tablesResult = await run(["ec2", "describe-route-tables"]);
+    if (tablesResult.exitCode !== 0) return { resources: {}, edges: [] };
+    const tables = (JSON.parse(tablesResult.stdout).RouteTables ?? []) as RawRouteTable[];
+
+    // Which table serves which subnet, and which is a VPC's main table — the
+    // two ways an instance's subnet resolves to routing.
+    const bySubnet = new Map<string, RawRouteTable>();
+    const mainByVpc = new Map<string, RawRouteTable>();
+    for (const table of tables) {
+      for (const association of table.Associations ?? []) {
+        if (association.SubnetId) bySubnet.set(association.SubnetId, table);
+        if (association.Main && table.VpcId) mainByVpc.set(table.VpcId, table);
+      }
+    }
+
+    // Security groups and launch templates the estate is guarded by (#1276).
+    // `effectiveIngress` resolved these from the declared graph alone, which is
+    // right until an instance sits in a group it did not declare — a shared
+    // group, one attached through someone else's launch template. Then the
+    // group is not a node, its rules are never read, and the instance reads as
+    // less exposed than it is. Under-reporting is the dangerous direction for a
+    // query whose whole purpose is finding what the internet can reach.
+    const declaredGroupIds = new Set(
+      Object.values(options.observed)
+        .filter((m) => m.type === "AWS::EC2::SecurityGroup" && m.physicalId)
+        .map((m) => m.physicalId as string),
+    );
+    const declaredTemplateIds = new Set(
+      Object.values(options.observed)
+        .filter((m) => m.type === "AWS::EC2::LaunchTemplate" && m.physicalId)
+        .map((m) => m.physicalId as string),
+    );
+    const groupsById = new Map<string, Record<string, unknown>>();
+    const wantedGroups = new Set<string>();
+    const templatesById = new Map<string, string[]>();
+
+    for (const [, meta] of instances) {
+      const where = placement.get(meta.physicalId as string);
+      if (!where) continue;
+      for (const id of where.securityGroupIds) if (!declaredGroupIds.has(id)) wantedGroups.add(id);
+      if (where.launchTemplateId && !declaredTemplateIds.has(where.launchTemplateId)) {
+        const versions = await run([
+          "ec2",
+          "describe-launch-template-versions",
+          "--launch-template-id",
+          where.launchTemplateId,
+          "--versions",
+          "$Latest",
+        ]);
+        if (versions.exitCode === 0) {
+          const templateGroups = (
+            (JSON.parse(versions.stdout).LaunchTemplateVersions ?? []) as Array<{
+              LaunchTemplateData?: { SecurityGroupIds?: string[] };
+            }>
+          ).flatMap((v) => v.LaunchTemplateData?.SecurityGroupIds ?? []);
+          templatesById.set(where.launchTemplateId, templateGroups);
+          for (const id of templateGroups) if (!declaredGroupIds.has(id)) wantedGroups.add(id);
+        }
+      }
+    }
+
+    if (wantedGroups.size > 0) {
+      const described = await run(["ec2", "describe-security-groups", "--group-ids", ...wantedGroups]);
+      if (described.exitCode === 0) {
+        for (const group of (JSON.parse(described.stdout).SecurityGroups ?? []) as Array<{
+          GroupId?: string;
+          VpcId?: string;
+          IpPermissions?: RawIpPermission[];
+        }>) {
+          if (!group.GroupId) continue;
+          groupsById.set(group.GroupId, {
+            GroupId: group.GroupId,
+            VpcId: group.VpcId,
+            SecurityGroupIngress: toIngressRules(group.IpPermissions ?? []),
+          });
+        }
+      }
+    }
+
+    const record = (
+      logicalId: string,
+      id: string,
+      type: string,
+      physicalId: string | undefined,
+      attrs: Record<string, unknown>,
+    ) => {
+      const existing = resources[id];
+      resources[id] = {
+        type,
+        status: "OBSERVED",
+        ...(physicalId ? { physicalId } : {}),
+        attributes: attrs,
+        ownership: "foreign",
+        referencedBy: [...new Set([...(existing?.referencedBy ?? []), logicalId])],
+      };
+    };
+
+    for (const [logicalId, meta] of instances) {
+      const where = placement.get(meta.physicalId as string);
+      if (!where) continue;
+
+      // Guarding first, and unconditionally: an instance with no internet route
+      // still has security groups, and `effectiveIngress` is asked about
+      // instances that are not internet-facing too.
+      for (const groupId of where.securityGroupIds) {
+        const attrs = groupsById.get(groupId);
+        if (!attrs) continue; // declared, or unreadable — either way not a dependency
+        record(logicalId, nodeId(groupId), "AWS::EC2::SecurityGroup", groupId, attrs);
+        edges.push({ from: logicalId, to: nodeId(groupId), kind: "ref", viaAttr: "SecurityGroupIds" });
+      }
+      const templateGroups = where.launchTemplateId ? templatesById.get(where.launchTemplateId) : undefined;
+      if (where.launchTemplateId && templateGroups) {
+        const templateNode = nodeId(where.launchTemplateId);
+        record(logicalId, templateNode, "AWS::EC2::LaunchTemplate", where.launchTemplateId, {
+          LaunchTemplateId: where.launchTemplateId,
+          LaunchTemplateData: { SecurityGroupIds: templateGroups },
+        });
+        edges.push({ from: logicalId, to: templateNode, kind: "ref", viaAttr: "LaunchTemplateId" });
+        for (const groupId of templateGroups) {
+          const attrs = groupsById.get(groupId);
+          if (!attrs) continue;
+          record(logicalId, nodeId(groupId), "AWS::EC2::SecurityGroup", groupId, attrs);
+          edges.push({ from: templateNode, to: nodeId(groupId), kind: "ref", viaAttr: "SecurityGroupIds" });
+        }
+      }
+
+      // Explicit subnet association first, else the VPC's main table — the two
+      // ways an instance's placement resolves to routing.
+      const table: RawRouteTable | undefined =
+        (where.subnetId ? bySubnet.get(where.subnetId) : undefined) ??
+        (where.vpcId ? mainByVpc.get(where.vpcId) : undefined);
+      if (!table?.RouteTableId) continue;
+
+      // Only routing that actually reaches the internet is worth reporting: an
+      // internal table adds a node and an edge and answers nothing.
+      const igwRoute = (table.Routes ?? []).find(
+        (route) =>
+          typeof route.GatewayId === "string" &&
+          route.GatewayId.startsWith("igw-") &&
+          (route.DestinationCidrBlock == null || route.DestinationCidrBlock === "0.0.0.0/0"),
+      );
+      if (!igwRoute?.GatewayId) continue;
+
+      const subnetNode = where.subnetId ? nodeId(where.subnetId) : undefined;
+      const tableNode = nodeId(table.RouteTableId);
+      const gatewayNode = nodeId(igwRoute.GatewayId);
+      const associationNode = `${tableNode}::assoc::${subnetNode ?? table.VpcId ?? "main"}`;
+      const routeNode = `${tableNode}::route::${gatewayNode}`;
+
+      if (subnetNode) record(logicalId, subnetNode, "AWS::EC2::Subnet", where.subnetId, { VpcId: where.vpcId });
+      record(logicalId, tableNode, "AWS::EC2::RouteTable", table.RouteTableId, { VpcId: table.VpcId });
+      record(logicalId, gatewayNode, "AWS::EC2::InternetGateway", igwRoute.GatewayId, {
+        InternetGatewayId: igwRoute.GatewayId,
+      });
+      record(logicalId, associationNode, "AWS::EC2::SubnetRouteTableAssociation", undefined, {
+        SubnetId: where.subnetId,
+        RouteTableId: table.RouteTableId,
+      });
+      record(logicalId, routeNode, "AWS::EC2::Route", undefined, {
+        RouteTableId: table.RouteTableId,
+        GatewayId: igwRoute.GatewayId,
+        DestinationCidrBlock: igwRoute.DestinationCidrBlock ?? "0.0.0.0/0",
+      });
+
+      // The chain enrichEffectiveTopology walks, reported explicitly rather
+      // than left to be reconstructed: an association and a route have no
+      // physical id of their own, so no identity index can resolve them.
+      if (subnetNode) {
+        edges.push({ from: logicalId, to: subnetNode, kind: "ref", viaAttr: "SubnetId" });
+        edges.push({ from: associationNode, to: subnetNode, kind: "ref", viaAttr: "SubnetId" });
+      }
+      edges.push({ from: associationNode, to: tableNode, kind: "ref", viaAttr: "RouteTableId" });
+      edges.push({ from: routeNode, to: tableNode, kind: "ref", viaAttr: "RouteTableId" });
+      edges.push({ from: routeNode, to: gatewayNode, kind: "ref", viaAttr: "GatewayId" });
+    }
+  } catch {
+    // Best-effort: the managed observation is complete and useful on its own,
+    // and failing it because an ambient dependency could not be read would
+    // trade a whole answer for a partial one.
+    return { resources: {}, edges: [] };
+  }
+
+  return { resources, edges };
+}