@intentius/chant-lexicon-aws 0.33.0 → 0.34.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-aws",
-  "version": "0.33.0",
+  "version": "0.34.0",
   "description": "AWS CloudFormation lexicon for chant — declarative IaC in TypeScript",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",
@@ -80,7 +80,7 @@
     "typescript": "^5.9.3"
   },
   "peerDependencies": {
-    "@intentius/chant": "^0.33.0",
+    "@intentius/chant": "^0.34.0",
     "typescript": "^5.9.3"
   }
 }

package/src/ambient.test.ts

@@ -0,0 +1,71 @@
+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 { observeAwsAmbient, canEnumerate } = await import("./ambient");
+
+const ok = (body: unknown) => ({ stdout: JSON.stringify(body), stderr: "", exitCode: 0 });
+const GROUPS = {
+  SecurityGroups: [
+    { GroupId: "sg-default", GroupName: "default", VpcId: "vpc-1" },
+    { GroupId: "sg-mine", GroupName: "web", VpcId: "vpc-1" },
+    { GroupId: "sg-stray", GroupName: "leftover", VpcId: "vpc-1" },
+  ],
+};
+
+// #1278 — a resource nothing points at is invisible to both other observation
+// paths, because both resolve outward from what is declared. "Which of my
+// security groups are unused" is a question about exactly those.
+describe("observeAwsAmbient (#1278)", () => {
+  beforeEach(() => spawnMock.mockReset());
+
+  it("reports groups that exist but are not managed", async () => {
+    spawnMock.mockResolvedValue(ok(GROUPS));
+    const found = await observeAwsAmbient({
+      kinds: ["AWS::EC2::SecurityGroup"],
+      observed: { web: { type: "AWS::EC2::SecurityGroup", status: "OK", physicalId: "sg-mine" } },
+    });
+    // sg-mine is managed, so it is not ambient — it would otherwise be counted twice.
+    expect(Object.keys(found).sort()).toEqual(["sg-default", "sg-stray"]);
+    expect(found["sg-default"]).toMatchObject({ ambient: true, ownership: "foreign" });
+  });
+
+  it("carries the whole payload, leaving 'unused' to the graph", async () => {
+    // Deciding attachment in the reader would put a conclusion in the
+    // observation — the mistake liveInternetFacing made and #1271 undid.
+    spawnMock.mockResolvedValue(ok(GROUPS));
+    const found = await observeAwsAmbient({ kinds: ["AWS::EC2::SecurityGroup"], observed: {} });
+    expect(found["sg-default"].attributes).toMatchObject({ GroupName: "default", VpcId: "vpc-1" });
+  });
+
+  it("is bounded by the kinds the project declares", async () => {
+    // A project managing security groups is not made to enumerate the account.
+    const found = await observeAwsAmbient({ kinds: ["AWS::S3::Bucket"], observed: {} });
+    expect(found).toEqual({});
+    expect(spawnMock).not.toHaveBeenCalled();
+  });
+
+  it("targets the stack's region", async () => {
+    spawnMock.mockResolvedValue(ok(GROUPS));
+    await observeAwsAmbient({ kinds: ["AWS::EC2::SecurityGroup"], observed: {}, region: "us-west-2" });
+    const argv = spawnMock.mock.calls[0][0] as string[];
+    expect(argv).toContain("--region");
+    expect(argv).toContain("us-west-2");
+  });
+
+  it("a failed enumeration yields nothing rather than throwing", async () => {
+    spawnMock.mockResolvedValue({ stdout: "", stderr: "denied", exitCode: 255 });
+    await expect(
+      observeAwsAmbient({ kinds: ["AWS::EC2::SecurityGroup"], observed: {} }),
+    ).resolves.toEqual({});
+  });
+
+  it("declares which kinds it can enumerate", () => {
+    expect(canEnumerate("AWS::EC2::SecurityGroup")).toBe(true);
+    expect(canEnumerate("AWS::EC2::Instance")).toBe(false);
+  });
+});

package/src/ambient.ts

@@ -0,0 +1,147 @@
+/**
+ * Resources that are simply *there* (#1278).
+ *
+ * `describeResources` answers "what do I manage" and `observeDependencies`
+ * answers "what do I rely on". Both resolve outward from the declared estate,
+ * so neither can see a resource nothing points at — and "which of my security
+ * groups are unused" is precisely a question about resources nothing points at.
+ *
+ * A state file cannot answer this at all: it knows what it created, and an
+ * unused resource is by definition not something it created and attached. A
+ * lexicon that can enumerate a kind can.
+ *
+ * Bounded by the kinds the project declares. A project managing security groups
+ * is asked about security groups, not about the account.
+ */
+
+import { applyAwsEndpointArgv } from "./components/cloud-executor";
+import type { ResourceMetadata } from "@intentius/chant/lexicon";
+
+/** Enumerable kinds, and how to list them. Extending this is the way to widen. */
+const ENUMERABLE: Record<string, { argv: string[]; key: string; id: string; name?: string }> = {
+  "AWS::EC2::SecurityGroup": {
+    argv: ["ec2", "describe-security-groups"],
+    key: "SecurityGroups",
+    id: "GroupId",
+    name: "GroupName",
+  },
+  // The account's default VPC is the archetype: nothing declares it, nothing
+  // in the declared estate points at it, and "which instances are outside a
+  // default VPC" cannot be answered without it.
+  "AWS::EC2::VPC": {
+    argv: ["ec2", "describe-vpcs"],
+    key: "Vpcs",
+    id: "VpcId",
+  },
+  // Nobody writes a network interface: EC2 creates one per instance. But the
+  // ENI is where a security group is actually attached, so "which of my
+  // security groups are unused" is an ENI question and cannot be answered
+  // without them. Asked exactly that, an agent queried
+  // `kind:EC2::NetworkInterface`, got nothing, and rebuilt the attachment map
+  // by hand from twenty-nine raw provider calls.
+  "AWS::EC2::NetworkInterface": {
+    argv: ["ec2", "describe-network-interfaces"],
+    key: "NetworkInterfaces",
+    id: "NetworkInterfaceId",
+  },
+};
+
+/**
+ * Kinds a declared kind implies, though nobody writes them.
+ *
+ * The scan is bounded by what the project declares — a project managing
+ * security groups is asked about security groups, not about the account. That
+ * bound is right, and it excluded exactly the resource that answers the
+ * question: EC2 creates a network interface per instance, and the ENI is where
+ * a security group is actually attached. So an estate full of instances had no
+ * ENIs recorded, and "which of my security groups are unused" — definitionally
+ * an ENI question — could not be answered from the snapshot at all.
+ *
+ * Declaring an instance is declaring its network interface. This widens the
+ * bound by implication rather than abandoning it: still nothing about the
+ * account at large.
+ */
+const IMPLIED: Record<string, string[]> = {
+  "AWS::EC2::Instance": ["AWS::EC2::NetworkInterface"],
+};
+
+/** The requested kinds, plus the ones they imply. */
+export function withImplied(kinds: string[]): string[] {
+  return [...new Set(kinds.flatMap((k) => [k, ...(IMPLIED[k] ?? [])]))];
+}
+
+/** The kinds this reader can enumerate. Declared so a caller can mention
+ * `--ambient` without paying for a scan to discover it is relevant. */
+export const AMBIENT_KINDS: string[] = Object.keys(ENUMERABLE);
+
+/** True when this lexicon can enumerate the kind, so a caller can say what it skipped. */
+export function canEnumerate(kind: string): boolean {
+  return kind in ENUMERABLE;
+}
+
+/**
+ * List resources of the declared kinds that exist in the account but are
+ * neither managed nor already observed.
+ *
+ * Attachment is deliberately NOT decided here. Whether a security group is
+ * "unused" is a graph question — does anything reference it — and the graph
+ * answers it once the group is a node. Deciding it in the reader would put a
+ * conclusion in the observation, which is the mistake `liveInternetFacing` made
+ * and #1271 undid.
+ */
+export async function observeAwsAmbient(options: {
+  kinds: string[];
+  observed: Record<string, ResourceMetadata>;
+  region?: string;
+}): Promise<Record<string, ResourceMetadata>> {
+  const kinds = withImplied(options.kinds).filter(canEnumerate);
+  if (kinds.length === 0) return {};
+
+  const { getRuntime } = await import("@intentius/chant/runtime-adapter");
+  const rt = getRuntime();
+  const regionArgs = options.region ? ["--region", options.region] : [];
+
+  // Physical ids already accounted for, so a managed resource is never also
+  // reported as ambient.
+  const known = new Set(
+    Object.values(options.observed)
+      .map((m) => m.physicalId)
+      .filter((id): id is string => typeof id === "string"),
+  );
+
+  const ambient: Record<string, ResourceMetadata> = {};
+  for (const kind of kinds) {
+    const spec = ENUMERABLE[kind];
+    try {
+      const result = await rt.spawn(
+        applyAwsEndpointArgv(["aws", ...spec.argv, ...regionArgs, "--output", "json"], process.env.AWS_ENDPOINT_URL),
+      );
+      if (result.exitCode !== 0) continue;
+      const rows = (JSON.parse(result.stdout)[spec.key] ?? []) as Array<Record<string, unknown>>;
+      for (const row of rows) {
+        const id = row[spec.id];
+        if (typeof id !== "string" || known.has(id)) continue;
+        ambient[id] = {
+          type: kind,
+          status: "OBSERVED",
+          physicalId: id,
+          // The whole payload, so the graph can decide what "unused" means
+          // rather than the reader pre-deciding it.
+          attributes: row,
+          ownership: "foreign",
+          ambient: true,
+        };
+      }
+    } catch {
+      // Best-effort per kind: one unreadable kind does not sink the others, and
+      // the managed observation is already complete without any of this.
+      continue;
+    }
+  }
+  // Same stamps the managed path applies, so one query shape works across both
+  // (#1279). Defaults matter most here: a default VPC or security group is
+  // ambient by definition — nobody declared it.
+  const { stampRegion } = await import("./properties");
+  const { stampProviderDefaults } = await import("./defaults");
+  return stampProviderDefaults(stampRegion(ambient, options.region));
+}

package/src/deep-observe.ts

@@ -246,6 +246,11 @@ export interface AwsDeepObserveOptions {
   entityNames: string[];
   entities?: Map<string, { entityType: string; props: Record<string, unknown> }>;
   stack?: string;
+  /** Region this stack is deployed in (#1267). Same reason the thin path takes
+   * one (#1261): without it a multi-region estate reads every stack against the
+   * ambient region, the out-of-region ones come back empty, and a deep snapshot
+   * silently records no properties for them. */
+  region?: string;
   owned?: boolean;
 }
 
@@ -270,9 +275,12 @@ export async function observeResourcesDeepAws(
   const stackName = options.stack ?? options.environment;
   const endpoint = process.env.AWS_ENDPOINT_URL;
 
+  const regionArgs = options.region ? ["--region", options.region] : [];
+
   const listResult = await rt.spawn(applyAwsEndpointArgv([
     "aws", "cloudformation", "describe-stack-resources",
     "--stack-name", stackName,
+    ...regionArgs,
     "--output", "json",
   ], endpoint));
 
@@ -334,6 +342,7 @@ export async function observeResourcesDeepAws(
       "aws", "cloudcontrol", "get-resource",
       "--type-name", type,
       "--identifier", identifier,
+      ...regionArgs,
       "--output", "json",
     ], endpoint));
 

package/src/defaults.test.ts

@@ -0,0 +1,73 @@
+import { describe, it, expect } from "vitest";
+import { stampProviderDefaults, canDetectDefault, DEFAULT_AWARE_KINDS } from "./defaults";
+import type { ResourceMetadata } from "@intentius/chant/lexicon";
+
+const res = (type: string, attributes: Record<string, unknown>): ResourceMetadata => ({
+  type,
+  status: "OBSERVED",
+  physicalId: "x",
+  attributes,
+});
+
+const flag = (type: string, attributes: Record<string, unknown>) =>
+  stampProviderDefaults({ r: res(type, attributes) }).r.attributes?.providerDefault;
+
+// Every account arrives with resources nobody wrote. Asked which security
+// groups were unused, agents split three ways on the same correct set of four,
+// because chant gave them no way to tell a VPC's default group from one someone
+// created.
+describe("provider defaults (#1278)", () => {
+  it("reads the marker AWS already sets, per kind", () => {
+    expect(flag("AWS::EC2::VPC", { IsDefault: true })).toBe(true);
+    expect(flag("AWS::EC2::Subnet", { DefaultForAz: true })).toBe(true);
+    expect(flag("AWS::EC2::NetworkAcl", { IsDefault: true })).toBe(true);
+    expect(flag("AWS::KMS::Key", { KeyManager: "AWS" })).toBe(true);
+    expect(flag("AWS::IAM::ManagedPolicy", { Arn: "arn:aws:iam::aws:policy/ReadOnlyAccess" })).toBe(true);
+  });
+
+  it("does not mark what the account holder created", () => {
+    expect(flag("AWS::EC2::VPC", { IsDefault: false })).toBeUndefined();
+    expect(flag("AWS::EC2::Subnet", { DefaultForAz: false })).toBeUndefined();
+    expect(flag("AWS::KMS::Key", { KeyManager: "CUSTOMER" })).toBeUndefined();
+    expect(flag("AWS::IAM::ManagedPolicy", { Arn: "arn:aws:iam::000000000000:policy/Mine" })).toBeUndefined();
+  });
+
+  it("treats the reserved group name as the marker it is", () => {
+    // AWS refuses `default` on create, so a group carrying it is the one AWS
+    // made with the VPC.
+    expect(flag("AWS::EC2::SecurityGroup", { GroupName: "default" })).toBe(true);
+    expect(flag("AWS::EC2::SecurityGroup", { GroupName: "default-web" })).toBeUndefined();
+    expect(flag("AWS::EC2::SecurityGroup", { GroupName: "webSecurityGroup" })).toBeUndefined();
+  });
+
+  it("finds the main route table through its associations", () => {
+    expect(flag("AWS::EC2::RouteTable", { Associations: [{ Main: true }] })).toBe(true);
+    expect(flag("AWS::EC2::RouteTable", { Associations: [{ Main: false }, { Main: true }] })).toBe(true);
+    expect(flag("AWS::EC2::RouteTable", { Associations: [{ Main: false }] })).toBeUndefined();
+    expect(flag("AWS::EC2::RouteTable", {})).toBeUndefined();
+  });
+
+  it("leaves a kind it cannot judge unmarked rather than guessing", () => {
+    // Absent means "not a default, or chant cannot tell". A blanket false would
+    // hide the difference.
+    expect(flag("AWS::EC2::Instance", { InstanceId: "i-1" })).toBeUndefined();
+    expect(canDetectDefault("AWS::EC2::Instance")).toBe(false);
+    expect(canDetectDefault("AWS::EC2::VPC")).toBe(true);
+  });
+
+  it("keeps every attribute it was given", () => {
+    const out = stampProviderDefaults({
+      r: res("AWS::EC2::SecurityGroup", { GroupName: "default", GroupId: "sg-1", region: "us-east-1" }),
+    }).r.attributes;
+    expect(out).toMatchObject({ GroupId: "sg-1", region: "us-east-1", providerDefault: true });
+  });
+
+  it("survives a payload it cannot read", () => {
+    expect(flag("AWS::EC2::RouteTable", { Associations: "not-a-list" })).toBeUndefined();
+  });
+
+  it("reports the kinds it can judge, so a caller need not guess", () => {
+    expect(DEFAULT_AWARE_KINDS).toContain("AWS::EC2::SecurityGroup");
+    expect(DEFAULT_AWARE_KINDS.every(canDetectDefault)).toBe(true);
+  });
+});

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();
+  });
+});