@intentius/chant-lexicon-aws 0.33.1 → 0.34.1

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