@intentius/chant-lexicon-aws 0.33.0 → 0.34.0

package/src/plugin.ts

@@ -1,6 +1,6 @@
 import { createRequire } from "module";
 import { detectTemplate } from "./detect";
-import type { LexiconPlugin, IntrinsicDef, ObservationResult, DeepObservationResult, ResourceMetadata, ExportedTemplate, ResourceSelector, InitTemplateSet, StackStatusObservation } from "@intentius/chant/lexicon";
+import type { LexiconPlugin, IntrinsicDef, ObservationResult, DeepObservationResult, DependencyObservation, ResourceMetadata, ExportedTemplate, ResourceSelector, InitTemplateSet, StackStatusObservation } from "@intentius/chant/lexicon";
 const require = createRequire(import.meta.url);
 import type { LintRule } from "@intentius/chant/lint/rule";
 import type { TemplateParser } from "@intentius/chant/import/parser";
@@ -19,6 +19,9 @@ import { applyAwsEndpointArgv } from "./components/cloud-executor";
 import { stackDoesNotExist } from "./stack-errors";
 import { awsDeepNormalizationHooks, observeResourcesDeepAws } from "./deep-observe";
 import { awsReferenceCatalog } from "./reference-catalog";
+import { AMBIENT_KINDS } from "./ambient";
+import { describeOwnProperties, stampRegion } from "./properties";
+import { stampProviderDefaults } from "./defaults";
 import { resolveTemplateAttrs } from "./live-attrs";
 import { CFParser } from "./import/parser";
 import { CFGenerator } from "./import/generator";
@@ -36,58 +39,8 @@ export { stackDoesNotExist } from "./stack-errors";
  * Provides serializer, lint rules, template detection,
  * import parsing, and code generation for AWS CloudFormation.
  */
-/**
- * Resolve `internetFacing` per instance LOGICAL id from LIVE route tables — a
- * subnet is internet-facing iff its route table (an explicit association, else
- * the VPC's main table) has a default route to an Internet Gateway. This covers
- * the account's default VPC, whose routing chant does not model declaratively
- * (the instance references it through a parameter). Best-effort: any failure
- * returns what it has, so search still works on the declared topology.
- */
-async function liveInternetFacing(regionArgs: string[], stackName: string): Promise<Record<string, string>> {
-  const { getRuntime } = await import("@intentius/chant/runtime-adapter");
-  const rt = getRuntime();
-  const run = (args: string[]) =>
-    rt.spawn(applyAwsEndpointArgv(["aws", ...args, ...regionArgs, "--output", "json"], process.env.AWS_ENDPOINT_URL));
-  const out: Record<string, string> = {};
-  try {
-    const res = await run(["cloudformation", "describe-stack-resources", "--stack-name", stackName]);
-    if (res.exitCode !== 0) return out;
-    const stackRes = (JSON.parse(res.stdout).StackResources ?? []) as Array<{ LogicalResourceId: string; ResourceType: string; PhysicalResourceId: string }>;
-    const instByLogical = new Map<string, string>();
-    for (const r of stackRes) if (r.ResourceType === "AWS::EC2::Instance") instByLogical.set(r.LogicalResourceId, r.PhysicalResourceId);
-    if (instByLogical.size === 0) return out;
-
-    const di = await run(["ec2", "describe-instances", "--instance-ids", ...instByLogical.values()]);
-    if (di.exitCode !== 0) return out;
-    const locByInst = new Map<string, { subnet?: string; vpc?: string }>();
-    for (const rsv of (JSON.parse(di.stdout).Reservations ?? []) as Array<{ Instances?: Array<{ InstanceId: string; SubnetId?: string; VpcId?: string }> }>)
-      for (const i of rsv.Instances ?? []) locByInst.set(i.InstanceId, { subnet: i.SubnetId, vpc: i.VpcId });
-
-    const rtRes = await run(["ec2", "describe-route-tables"]);
-    if (rtRes.exitCode !== 0) return out;
-    const subnetIgw = new Map<string, string>();
-    const vpcMainIgw = new Map<string, string>();
-    for (const t of (JSON.parse(rtRes.stdout).RouteTables ?? []) as Array<{ RouteTableId?: string; VpcId?: string; Routes?: Array<{ GatewayId?: string }>; Associations?: Array<{ SubnetId?: string; Main?: boolean }> }>) {
-      const igwRoute = (t.Routes ?? []).find((r) => typeof r.GatewayId === "string" && r.GatewayId.startsWith("igw-"));
-      if (!igwRoute) continue;
-      const ev = `${t.RouteTableId ?? "rtb"} → ${igwRoute.GatewayId}`;
-      for (const a of t.Associations ?? []) {
-        if (a.SubnetId) subnetIgw.set(a.SubnetId, ev);
-        if (a.Main && t.VpcId) vpcMainIgw.set(t.VpcId, ev);
-      }
-    }
-
-    for (const [logical, instId] of instByLogical) {
-      const loc = locByInst.get(instId);
-      const ev = loc ? ((loc.subnet && subnetIgw.get(loc.subnet)) || (loc.vpc && vpcMainIgw.get(loc.vpc))) : undefined;
-      if (ev) out[logical] = ev;
-    }
-  } catch {
-    /* best-effort */
-  }
-  return out;
-}
+/** #1265 — the ownership notice is about the environment, so it is said once. */
+let warnedOwnership = false;
 
 export const awsPlugin: LexiconPlugin = {
   name: "aws",
@@ -598,10 +551,17 @@ aws cloudformation wait stack-update-complete --stack-name my-app-prod`,
     if (options.owned) {
       // describe-stack-resources does not return tags, so ownership cannot be
       // determined here. Degrade to detect-only rather than silently filtering.
-      // eslint-disable-next-line no-console
-      console.warn(
+      //
+      // Once per process, not once per stack (#1265). It is a property of the
+      // environment, not of each stack, and a four-stack project printed four
+      // identical copies ahead of every answer — enough that an agent piping
+      // `graph --format ir` with `2>&1` had to skip lines to find the JSON.
+      warnedOwnership ||
+        // eslint-disable-next-line no-console
+        console.warn(
         "[aws] ownership filter unavailable on describeResources (no tags from describe-stack-resources) — returning all, each with an explicit `unknown` verdict; use `chant import --from <env> --owned` for ownership-filtered export",
-      );
+        );
+      warnedOwnership = true;
     }
 
     // Derive stack name. A multi-stack project passes the explicit CloudFormation
@@ -708,10 +668,17 @@ aws cloudformation wait stack-update-complete --stack-name my-app-prod`,
       };
     }
 
+    // Each resource's OWN properties, on top of the stack outputs above (#1279).
+    // Until this, a node's `attrs` were the stack's exports replicated onto
+    // every member, so no instance carried its own `VpcId`.
+    const withProperties = stampProviderDefaults(
+      stampRegion(await describeOwnProperties(resources, options.region), options.region),
+    );
+
     // Every entity the stack answered for was answered for: an entity the
     // template doesn't carry is genuinely not in this stack, which is an
     // absence, not a hole.
-    return observation(resources);
+    return observation(withProperties);
   },
 
   /**
@@ -719,12 +686,52 @@ aws cloudformation wait stack-update-complete --stack-name my-app-prod`,
    * CloudFormation's view of the world, into the resource as the service
    * actually holds it. Implementation in ./deep-observe.ts.
    */
+  /**
+   * The routing this estate depends on but does not declare (#1273) — an
+   * instance in the account's default VPC routes through a table nobody wrote.
+   * Reporting the resources lets the graph fold derive `internetFacing`, rather
+   * than this lexicon computing it and injecting the conclusion.
+   */
+  async observeDependencies(options: {
+    environment: string;
+    entities: Map<string, { entityType: string; props: Record<string, unknown> }>;
+    observed: Record<string, ResourceMetadata>;
+    stack?: string;
+    region?: string;
+  }): Promise<DependencyObservation> {
+    const { observeAwsDependencies } = await import("./dependencies");
+    return observeAwsDependencies({ observed: options.observed, region: options.region });
+  },
+
+  /**
+   * Resources of a managed kind that exist without being declared or
+   * referenced (#1278) — the account's default security groups, an unattached
+   * one someone left behind. Nothing else in the observation can see them,
+   * because everything else resolves outward from what is declared.
+   */
+  /** #1278 — the kinds `observeAmbient` can enumerate, from the same source. */
+  ambientKinds(): string[] {
+    return AMBIENT_KINDS;
+  },
+
+  async observeAmbient(options: {
+    environment: string;
+    kinds: string[];
+    observed: Record<string, ResourceMetadata>;
+    stack?: string;
+    region?: string;
+  }): Promise<Record<string, ResourceMetadata>> {
+    const { observeAwsAmbient } = await import("./ambient");
+    return observeAwsAmbient({ kinds: options.kinds, observed: options.observed, region: options.region });
+  },
+
   async observeResourcesDeep(options: {
     environment: string;
     buildOutput: string;
     entityNames: string[];
     entities: Map<string, { entityType: string; props: Record<string, unknown> }>;
     stack?: string;
+    region?: string;
     owned?: boolean;
   }): Promise<DeepObservationResult> {
     return observeResourcesDeepAws({
@@ -732,6 +739,7 @@ aws cloudformation wait stack-update-complete --stack-name my-app-prod`,
       entityNames: options.entityNames,
       entities: options.entities,
       stack: options.stack,
+      region: options.region,
       owned: options.owned,
     });
   },
@@ -827,13 +835,6 @@ aws cloudformation wait stack-update-complete --stack-name my-app-prod`,
         for (const [logicalId, v] of Object.entries(attrs)) {
           merged[multi ? `${ref.name}::${logicalId}` : logicalId] = v;
         }
-        // Resolve internetFacing from live route tables (covers the default VPC),
-        // carrying the route-table → IGW evidence so search can justify the match.
-        const facing = await liveInternetFacing(ref.region ? ["--region", ref.region] : [], ref.name);
-        for (const [logicalId, via] of Object.entries(facing)) {
-          const key = multi ? `${ref.name}::${logicalId}` : logicalId;
-          merged[key] = { ...merged[key], internetFacing: true, internetFacingVia: via };
-        }
       } catch {
         // A stack that isn't deployed yet contributes no live attrs — skip it.
       }

package/src/properties.test.ts

@@ -0,0 +1,113 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+
+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 { describeOwnProperties, canDescribe, stampRegion } = await import("./properties");
+
+const ok = (body: unknown) => ({ stdout: JSON.stringify(body), stderr: "", exitCode: 0 });
+const fail = { stdout: "", stderr: "InvalidInstanceID.NotFound", exitCode: 255 };
+
+const instance = (id: string, vpc: string) => ({ InstanceId: id, VpcId: vpc });
+const reservations = (...rows: Array<Record<string, unknown>>) => ({
+  Reservations: [{ Instances: rows }],
+});
+
+// #1279 — `describe-stack-resources` returns identity and nothing about the
+// resource, so the observation had been filling `attributes` with the *stack's*
+// outputs, copied onto every member. No node carried its own VpcId.
+describe("describeOwnProperties (#1279)", () => {
+  beforeEach(() => spawnMock.mockReset());
+
+  const observed = {
+    web: { type: "AWS::EC2::Instance", status: "OK", physicalId: "i-1" },
+    api: { type: "AWS::EC2::Instance", status: "OK", physicalId: "i-2" },
+  };
+
+  it("joins each resource's own properties back by physical id", async () => {
+    spawnMock.mockResolvedValue(ok(reservations(instance("i-1", "vpc-a"), instance("i-2", "vpc-b"))));
+    const merged = await describeOwnProperties(observed);
+    expect(merged.web.attributes?.VpcId).toBe("vpc-a");
+    expect(merged.api.attributes?.VpcId).toBe("vpc-b");
+  });
+
+  it("reads a kind once for the whole observation, not once per resource", async () => {
+    spawnMock.mockResolvedValue(ok(reservations(instance("i-1", "vpc-a"), instance("i-2", "vpc-b"))));
+    await describeOwnProperties(observed);
+    expect(spawnMock).toHaveBeenCalledTimes(1);
+  });
+
+  it("keeps stack outputs, and lets the resource's own property win the name", async () => {
+    const withOutputs = {
+      web: {
+        type: "AWS::EC2::Instance",
+        status: "OK",
+        physicalId: "i-1",
+        attributes: { expVpcId: "vpc-exported", VpcId: "stale" },
+      },
+    };
+    spawnMock.mockResolvedValue(ok(reservations(instance("i-1", "vpc-a"))));
+    const merged = await describeOwnProperties(withOutputs);
+    expect(merged.web.attributes?.expVpcId).toBe("vpc-exported");
+    expect(merged.web.attributes?.VpcId).toBe("vpc-a");
+  });
+
+  it("falls back to one call per id when the batch fails on a single bad id", async () => {
+    // AWS fails the whole call on one unknown id. A snapshot naming an instance
+    // that has since been terminated would otherwise take every other
+    // instance's properties down with it — and the empty result is
+    // indistinguishable from "the account has nothing to say".
+    spawnMock
+      .mockResolvedValueOnce(fail) // the batch, killed by i-2
+      .mockResolvedValueOnce(ok(reservations(instance("i-1", "vpc-a"))))
+      .mockResolvedValueOnce(fail); // i-2 really is gone
+    const merged = await describeOwnProperties(observed);
+    expect(merged.web.attributes?.VpcId).toBe("vpc-a");
+    expect(merged.api.attributes).toBeUndefined();
+  });
+
+  it("leaves the observation untouched when the kind cannot be read at all", async () => {
+    spawnMock.mockResolvedValue(fail);
+    const merged = await describeOwnProperties({ web: observed.web });
+    expect(merged.web.attributes).toBeUndefined();
+  });
+
+  it("does not call out for a kind it cannot describe", async () => {
+    const merged = await describeOwnProperties({
+      fn: { type: "AWS::Lambda::Function", status: "OK", physicalId: "fn-1" },
+    });
+    expect(spawnMock).not.toHaveBeenCalled();
+    expect(merged.fn.attributes).toBeUndefined();
+    expect(canDescribe("AWS::Lambda::Function")).toBe(false);
+  });
+});
+
+// #1279 — the observation is scoped per stack and each stack declares its
+// region, so the reader knew this and threw it away.
+describe("stampRegion (#1279)", () => {
+  const one = { web: { type: "AWS::EC2::Instance", status: "OK", physicalId: "i-1" } };
+
+  it("records the region the resource was observed in", () => {
+    expect(stampRegion(one, "us-west-2").web.attributes?.region).toBe("us-west-2");
+  });
+
+  it("keeps the properties already read", () => {
+    const withProps = { web: { ...one.web, attributes: { VpcId: "vpc-a" } } };
+    const out = stampRegion(withProps, "us-west-2").web.attributes;
+    expect(out).toMatchObject({ VpcId: "vpc-a", region: "us-west-2" });
+  });
+
+  it("falls back to the region the call would have used", () => {
+    const prev = process.env.AWS_REGION;
+    process.env.AWS_REGION = "eu-west-1";
+    try {
+      expect(stampRegion(one).web.attributes?.region).toBe("eu-west-1");
+    } finally {
+      if (prev === undefined) delete process.env.AWS_REGION;
+      else process.env.AWS_REGION = prev;
+    }
+  });
+});

package/src/properties.ts

@@ -0,0 +1,166 @@
+/**
+ * A managed resource's own properties (#1279).
+ *
+ * `describe-stack-resources` returns identity and status — logical id, physical
+ * id, type, timestamp — and nothing about the resource itself. So the managed
+ * observation filled `attributes` with the *stack's* outputs instead, copied
+ * onto every resource in the stack. Every node in a stack came out carrying the
+ * same `expVpcId`/`expWebIp` keys, and no node carried its own `VpcId`.
+ *
+ * That is invisible until something asks. `search --show VpcId` printed a blank
+ * column for six instances, which reads as "the estate has no VPCs" rather than
+ * "chant never read that". An agent asked which instances were outside the
+ * default VPC concluded all six were, because nothing in the graph said
+ * otherwise.
+ *
+ * A deep read (Cloud Control) answers this properly but is a per-resource call
+ * and is not available on every endpoint. This is the cheap middle: one describe
+ * per kind for the whole observation, joined back by physical id. Stack outputs
+ * are kept — they were the only attributes for a long time and queries lean on
+ * them — but a resource's own properties win a name collision, because they are
+ * the resource's.
+ */
+
+import { applyAwsEndpointArgv } from "./components/cloud-executor";
+import type { ResourceMetadata } from "@intentius/chant/lexicon";
+
+/**
+ * How to read each kind in bulk, and which field joins back to the physical id.
+ *
+ * Extending this is the way to widen coverage. Deliberately batch calls: one
+ * `describe-instances` for every instance in the stack, not one per instance.
+ */
+const DESCRIBE: Record<
+  string,
+  { argv: string[]; idFlag: string; key: string; id: string; nested?: string }
+> = {
+  "AWS::EC2::Instance": {
+    argv: ["ec2", "describe-instances"],
+    idFlag: "--instance-ids",
+    key: "Reservations",
+    nested: "Instances",
+    id: "InstanceId",
+  },
+  "AWS::EC2::VPC": { argv: ["ec2", "describe-vpcs"], idFlag: "--vpc-ids", key: "Vpcs", id: "VpcId" },
+  "AWS::EC2::Subnet": {
+    argv: ["ec2", "describe-subnets"],
+    idFlag: "--subnet-ids",
+    key: "Subnets",
+    id: "SubnetId",
+  },
+  "AWS::EC2::SecurityGroup": {
+    argv: ["ec2", "describe-security-groups"],
+    idFlag: "--group-ids",
+    key: "SecurityGroups",
+    id: "GroupId",
+  },
+};
+
+/**
+ * Stamp the region each resource was observed in (#1279).
+ *
+ * The observation is already scoped per stack and each stack declares its
+ * region, so the reader knows this and was throwing it away. Without it the
+ * only route to "which region is this in" was parsing
+ * `Placement.AvailabilityZone` and trimming the last character — a trick that
+ * happens to work for EC2 and for nothing else. Region is a dimension of the
+ * estate, not a substring of an availability zone.
+ */
+export function stampRegion(
+  resources: Record<string, ResourceMetadata>,
+  region?: string,
+): Record<string, ResourceMetadata> {
+  // Fall back to the region the call would actually have used, so a
+  // single-region project gets the same attribute a multi-region one does.
+  const value = region ?? process.env.AWS_REGION ?? process.env.AWS_DEFAULT_REGION;
+  if (!value) return resources;
+  const stamped: Record<string, ResourceMetadata> = {};
+  for (const [name, meta] of Object.entries(resources)) {
+    stamped[name] = { ...meta, attributes: { ...(meta.attributes ?? {}), region: value } };
+  }
+  return stamped;
+}
+
+/** True when this lexicon can read the kind's own properties. */
+export function canDescribe(kind: string): boolean {
+  return kind in DESCRIBE;
+}
+
+/**
+ * Merge each resource's own properties into an observation, in place of nothing.
+ *
+ * Best-effort per kind, and per kind only: an endpoint that cannot answer
+ * `describe-subnets` still yields instance properties, and a total failure
+ * leaves the observation exactly as it arrived. The managed observation is
+ * already complete without any of this — these are additional facts about
+ * resources chant has already identified, so a miss costs detail, never
+ * correctness.
+ */
+export async function describeOwnProperties(
+  resources: Record<string, ResourceMetadata>,
+  region?: string,
+): Promise<Record<string, ResourceMetadata>> {
+  // Group the physical ids to look up by kind, so each kind is one call.
+  const wanted = new Map<string, Map<string, string[]>>();
+  for (const [name, meta] of Object.entries(resources)) {
+    if (!meta.physicalId || !canDescribe(meta.type)) continue;
+    const byId = wanted.get(meta.type) ?? new Map<string, string[]>();
+    byId.set(meta.physicalId, [...(byId.get(meta.physicalId) ?? []), name]);
+    wanted.set(meta.type, byId);
+  }
+  if (wanted.size === 0) return resources;
+
+  const { getRuntime } = await import("@intentius/chant/runtime-adapter");
+  const rt = getRuntime();
+  const regionArgs = region ? ["--region", region] : [];
+  const merged = { ...resources };
+
+  /** One describe for a set of ids. `null` when the call itself failed. */
+  const read = async (spec: (typeof DESCRIBE)[string], ids: string[]) => {
+    const result = await rt.spawn(
+      applyAwsEndpointArgv(
+        ["aws", ...spec.argv, spec.idFlag, ...ids, ...regionArgs, "--output", "json"],
+        process.env.AWS_ENDPOINT_URL,
+      ),
+    );
+    if (result.exitCode !== 0) return null;
+    return (JSON.parse(result.stdout)[spec.key] ?? []) as Array<Record<string, unknown>>;
+  };
+
+  for (const [kind, byId] of wanted) {
+    const spec = DESCRIBE[kind];
+    try {
+      const ids = [...byId.keys()];
+      let top = await read(spec, ids);
+      // AWS fails the whole call on one bad id — a snapshot naming an instance
+      // that has since been terminated takes every other instance's properties
+      // down with it, and the result is indistinguishable from "the account has
+      // nothing to say". Retry one at a time so the damage stops at the bad id.
+      if (top === null && ids.length > 1) {
+        top = [];
+        for (const id of ids) top.push(...((await read(spec, [id])) ?? []));
+      }
+      if (top === null) continue;
+      // `describe-instances` buries instances one level down under reservations;
+      // the others return the resources directly.
+      const rows = spec.nested
+        ? top.flatMap((r) => (r[spec.nested as string] ?? []) as Array<Record<string, unknown>>)
+        : top;
+      for (const row of rows) {
+        const id = row[spec.id];
+        if (typeof id !== "string") continue;
+        for (const name of byId.get(id) ?? []) {
+          merged[name] = {
+            ...merged[name],
+            // Own properties last: a resource's `VpcId` outranks a stack output
+            // that happens to share the name.
+            attributes: { ...(merged[name].attributes ?? {}), ...row },
+          };
+        }
+      }
+    } catch {
+      continue;
+    }
+  }
+  return merged;
+}

package/src/reference-catalog.ts

@@ -16,10 +16,12 @@ export const awsReferenceCatalog: ReferenceCatalog = {
     { kind: "AWS::EC2::VPC", ids: ["VpcId"] },
     { kind: "AWS::EC2::Subnet", ids: ["SubnetId"] },
     { kind: "AWS::EC2::SecurityGroup", ids: ["GroupId"] },
+    { kind: "AWS::EC2::NetworkInterface", ids: ["NetworkInterfaceId"] },
     { kind: "AWS::EC2::Instance", ids: ["InstanceId"] },
     { kind: "AWS::EC2::InternetGateway", ids: ["InternetGatewayId"] },
     { kind: "AWS::EC2::NatGateway", ids: ["NatGatewayId"] },
     { kind: "AWS::EC2::RouteTable", ids: ["RouteTableId"] },
+    { kind: "AWS::EC2::LaunchTemplate", ids: ["LaunchTemplateId", "LaunchTemplateName"] },
     { kind: "AWS::ElasticLoadBalancingV2::LoadBalancer", ids: ["LoadBalancerArn", "DNSName"] },
     { kind: "AWS::ElasticLoadBalancingV2::TargetGroup", ids: ["TargetGroupArn"] },
     { kind: "AWS::ECS::Cluster", ids: ["ClusterArn", "ClusterName"] },
@@ -32,7 +34,7 @@ export const awsReferenceCatalog: ReferenceCatalog = {
     { from: "AWS::EC2::Subnet", path: "VpcId", targetKind: "AWS::EC2::VPC", relation: "containment", label: "in VPC" },
     { from: "AWS::EC2::SecurityGroup", path: "VpcId", targetKind: "AWS::EC2::VPC", relation: "containment", label: "in VPC" },
     { from: "AWS::EC2::RouteTable", path: "VpcId", targetKind: "AWS::EC2::VPC", relation: "containment", label: "in VPC" },
-    { from: "AWS::EC2::Instance", path: "SubnetId", targetKind: "AWS::EC2::Subnet", relation: "containment", label: "in subnet" },
+    { from: "AWS::EC2::Instance", path: "SubnetId", targetKind: "AWS::EC2::Subnet", relation: "containment", label: "in subnet", viaAttr: "SubnetId" },
     { from: "AWS::EC2::NatGateway", path: "SubnetId", targetKind: "AWS::EC2::Subnet", relation: "containment", label: "in subnet" },
     { from: "AWS::ElasticLoadBalancingV2::LoadBalancer", path: "AvailabilityZones[].SubnetId", targetKind: "AWS::EC2::Subnet", relation: "containment", label: "in subnet" },
     { from: "AWS::ElasticLoadBalancingV2::TargetGroup", path: "VpcId", targetKind: "AWS::EC2::VPC", relation: "containment", label: "in VPC" },
@@ -40,9 +42,28 @@ export const awsReferenceCatalog: ReferenceCatalog = {
     { from: "AWS::RDS::DBInstance", path: "DBSubnetGroup.Subnets[].SubnetIdentifier", targetKind: "AWS::EC2::Subnet", relation: "containment", label: "in subnet" },
 
     // ── references (→ edges) ──
-    { from: "AWS::EC2::Instance", path: "SecurityGroups[].GroupId", targetKind: "AWS::EC2::SecurityGroup", relation: "reference", label: "sg" },
+    { from: "AWS::EC2::Instance", path: "SecurityGroups[].GroupId", targetKind: "AWS::EC2::SecurityGroup", relation: "reference", label: "sg", viaAttr: "SecurityGroupIds" },
+    { from: "AWS::EC2::Instance", path: "SecurityGroupIds[]", targetKind: "AWS::EC2::SecurityGroup", relation: "reference", label: "sg", viaAttr: "SecurityGroupIds" },
+    // Security groups reached indirectly, through a launch template — the hop a
+    // flat describe-instances sweep misses, and the reason `effectiveIngress`
+    // exists as a fold rather than a passthrough.
+    { from: "AWS::EC2::Instance", path: "LaunchTemplate.LaunchTemplateId", targetKind: "AWS::EC2::LaunchTemplate", relation: "reference", label: "from template", viaAttr: "LaunchTemplateId" },
+    { from: "AWS::EC2::Instance", path: "LaunchTemplateId", targetKind: "AWS::EC2::LaunchTemplate", relation: "reference", label: "from template", viaAttr: "LaunchTemplateId" },
+    { from: "AWS::EC2::LaunchTemplate", path: "LaunchTemplateData.SecurityGroupIds[]", targetKind: "AWS::EC2::SecurityGroup", relation: "reference", label: "sg", viaAttr: "SecurityGroupIds" },
+    { from: "AWS::EC2::LaunchTemplate", path: "SecurityGroupIds[]", targetKind: "AWS::EC2::SecurityGroup", relation: "reference", label: "sg", viaAttr: "SecurityGroupIds" },
+    // The routing chain `internetFacing` walks. Route and association carry no
+    // physical id of their own, so they are only ever the `from` side.
+    { from: "AWS::EC2::Route", path: "RouteTableId", targetKind: "AWS::EC2::RouteTable", relation: "reference", label: "in table", viaAttr: "RouteTableId" },
+    { from: "AWS::EC2::SubnetRouteTableAssociation", path: "SubnetId", targetKind: "AWS::EC2::Subnet", relation: "reference", label: "associates", viaAttr: "SubnetId" },
+    { from: "AWS::EC2::SubnetRouteTableAssociation", path: "RouteTableId", targetKind: "AWS::EC2::RouteTable", relation: "reference", label: "to table", viaAttr: "RouteTableId" },
     { from: "AWS::EC2::SecurityGroup", path: "IpPermissions[].UserIdGroupPairs[].GroupId", targetKind: "AWS::EC2::SecurityGroup", relation: "reference", label: "allows" },
-    { from: "AWS::EC2::Route", path: "GatewayId", targetKind: "AWS::EC2::InternetGateway", relation: "reference", label: "via" },
+    // An ENI is where a security group is attached and where an instance's
+    // networking actually lives, so both edges are what make "unused" and
+    // "reachable" answerable from the graph rather than from a provider sweep.
+    { from: "AWS::EC2::NetworkInterface", path: "Groups[].GroupId", targetKind: "AWS::EC2::SecurityGroup", relation: "reference", label: "sg", viaAttr: "Groups" },
+    { from: "AWS::EC2::NetworkInterface", path: "Attachment.InstanceId", targetKind: "AWS::EC2::Instance", relation: "reference", label: "attached to", viaAttr: "Attachment" },
+    { from: "AWS::EC2::NetworkInterface", path: "SubnetId", targetKind: "AWS::EC2::Subnet", relation: "containment", label: "in subnet" },
+    { from: "AWS::EC2::Route", path: "GatewayId", targetKind: "AWS::EC2::InternetGateway", relation: "reference", label: "via", viaAttr: "GatewayId" },
     { from: "AWS::EC2::Route", path: "NatGatewayId", targetKind: "AWS::EC2::NatGateway", relation: "reference", label: "via" },
     { from: "AWS::ElasticLoadBalancingV2::LoadBalancer", path: "SecurityGroups[]", targetKind: "AWS::EC2::SecurityGroup", relation: "reference", label: "sg" },
     { from: "AWS::ElasticLoadBalancingV2::Listener", path: "LoadBalancerArn", targetKind: "AWS::ElasticLoadBalancingV2::LoadBalancer", relation: "reference", label: "on" },