@intentius/chant-lexicon-aws 0.124.45 → 0.124.46

package/dist/capabilities/mapping.json

@@ -0,0 +1,150 @@
+{
+    "lexicon": "aws",
+    "types": "kind",
+    "refs": "cloudformation",
+    "labels": {
+        "AWS::EC2::VPC": "Vpc",
+        "AWS::EC2::NetworkInterface": "NetworkInterface",
+        "AWS::EC2::Volume": "Volume",
+        "AWS::Lambda::Function": "Function",
+        "AWS::Lambda::Url": "FunctionUrl",
+        "AWS::IAM::InstanceProfile": "InstanceProfile",
+        "AWS::IAM::Role": "Role",
+        "AWS::IAM::Policy": "Policy",
+        "AWS::IAM::ManagedPolicy": "Policy",
+        "AWS::S3::BucketPolicy": "ResourcePolicy",
+        "AWS::SQS::QueuePolicy": "ResourcePolicy",
+        "AWS::S3::Bucket": "Bucket",
+        "AWS::DynamoDB::Table": "Table",
+        "AWS::DynamoDB::GlobalTable": "Table",
+        "AWS::RDS::DBInstance": "Database",
+        "AWS::RDS::DBCluster": "Database",
+        "AWS::SecretsManager::Secret": "Secret",
+        "AWS::SQS::Queue": "Queue",
+        "AWS::EFS::FileSystem": "FileSystem",
+        "AWS::SSM::Parameter": "Parameter",
+        "AWS::ECS::Service": "Service",
+        "AWS::ECS::TaskDefinition": "TaskDefinition",
+        "AWS::RDS::DBSubnetGroup": "SubnetGroup",
+        "AWS::EC2::NatGateway": "NatGateway",
+        "AWS::ElasticLoadBalancingV2::LoadBalancer": "LoadBalancer"
+    },
+    "edges": {
+        "Instance": {
+            "IamInstanceProfile": "profile",
+            "VpcId": "vpc"
+        },
+        "LaunchTemplate": {
+            "LaunchTemplateData": {
+                "InstanceProfile": "profile"
+            }
+        },
+        "Subnet": {
+            "VpcId": "vpc"
+        },
+        "SecurityGroup": {
+            "VpcId": "vpc"
+        },
+        "NetworkInterface": {
+            "SubnetId": "subnet",
+            "GroupSet": "sg"
+        },
+        "Database": {
+            "VPCSecurityGroups": "sg",
+            "VpcSecurityGroupIds": "sg",
+            "DBSubnetGroupName": "subnetGroup"
+        },
+        "Function": {
+            "Role": "role",
+            "VpcConfig": {
+                "SecurityGroup": "sg",
+                "Subnet": "subnet"
+            }
+        },
+        "FunctionUrl": {
+            "TargetFunctionArn": "function"
+        },
+        "InstanceProfile": {
+            "Roles": "role"
+        },
+        "Policy": {
+            "Roles": "attachedTo"
+        },
+        "Role": {
+            "ManagedPolicyArns": "-attachedTo"
+        },
+        "ResourcePolicy": {
+            "Bucket": "policyOf",
+            "Queues": "policyOf"
+        },
+        "Service": {
+            "TaskDefinition": "task",
+            "NetworkConfiguration": {
+                "SecurityGroup": "sg",
+                "Subnet": "subnet"
+            }
+        },
+        "TaskDefinition": {
+            "TaskRoleArn": "role"
+        },
+        "SubnetGroup": {
+            "SubnetIds": "subnet"
+        },
+        "NatGateway": {
+            "SubnetId": "subnet"
+        },
+        "LoadBalancer": {
+            "Subnets": "subnet",
+            "SecurityGroups": "sg"
+        }
+    },
+    "attrs": {
+        "FunctionUrl": {
+            "authType": "AuthType"
+        },
+        "Role": {
+            "name": "RoleName"
+        },
+        "Bucket": {
+            "name": "BucketName",
+            "acl": "AccessControl",
+            "blockPublicPolicy": "PublicAccessBlockConfiguration.BlockPublicPolicy"
+        },
+        "Table": {
+            "name": "TableName"
+        },
+        "Database": {
+            "encrypted": "StorageEncrypted"
+        },
+        "FileSystem": {
+            "encrypted": "Encrypted"
+        },
+        "Volume": {
+            "encrypted": "Encrypted"
+        },
+        "Parameter": {
+            "paramType": "Type"
+        },
+        "Vpc": {
+            "isDefault": "IsDefault"
+        }
+    },
+    "documents": {
+        "Role": {
+            "AssumeRolePolicyDocument": "trust",
+            "Policies[].PolicyDocument": "permission"
+        },
+        "Policy": {
+            "PolicyDocument": "permission"
+        },
+        "ResourcePolicy": {
+            "PolicyDocument": "resource"
+        }
+    },
+    "tags": [
+        "Tags"
+    ],
+    "classificationTags": [
+        "data-classification"
+    ]
+}

package/dist/capabilities/pack.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The aws lexicon's capability pack (#4375): its mapping of CloudFormation
+ * kinds onto the lexicon-neutral view the capability rules read. All data;
+ * CloudFormation policy documents are JSON already, so no adapter code.
+ */
+import type { CapabilityPack } from "@intentius/chant/capabilities/view";
+export declare const awsCapabilityPack: CapabilityPack;
+//# sourceMappingURL=pack.d.ts.map

package/dist/capabilities/pack.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pack.d.ts","sourceRoot":"","sources":["../../src/capabilities/pack.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAqB,cAAc,EAAE,MAAM,oCAAoC,CAAC;AAG5F,eAAO,MAAM,iBAAiB,EAAE,cAA0D,CAAC"}

package/dist/capabilities/pack.js

@@ -0,0 +1,2 @@
+import mapping from "./mapping.json" with { type: "json" };
+export const awsCapabilityPack = { mapping: mapping };

package/dist/integrity.json

@@ -1,7 +1,7 @@
 {
   "algorithm": "sha256",
   "artifacts": {
-    "manifest.json": "4e87272580ed7978235350ce2c7631c83b575c7bc765f3c27002e63bc02c18b6",
+    "manifest.json": "8c88e8750ff98569d97921403ae44dfba0065e512d6dee2de6a912897cd84e66",
     "meta.json": "6f48557ed4203cbdeafdb47e7270fdf3533f6d6e6189987246301ed8e72170e9",
     "types/index.d.ts": "8651f9ae166668f4311eea1fe61c3fe235f345947951c1d23d1df24a4fd3384f",
     "rules/hardcoded-region.ts": "957eadcaa9f39cc17d21437565d7a94607d9b082cf28918b178fa067f07498a9",
@@ -75,5 +75,5 @@
     "skills/chant-aws-eks.md": "8789255709ff004ad0a875fd5999edcdc66fc6e33d710db058d9f42703bcfdfe",
     "skills/chant-aws-carve-terraform.md": "8780b94ce60aded935938d5ef20ea667738354051da1bf9ca6d70d9886f65d21"
   },
-  "composite": "6e6034cc52fcfa710c8daa010fd67a0f510a61a93cf862910a0b85791d67d96f"
+  "composite": "c3e022363a232d4ee358a6f31700ecb1ee3d51b871d2a1efddb4655291562233"
 }

package/dist/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "aws",
-  "version": "0.124.45",
+  "version": "0.124.46",
   "chantVersion": ">=0.1.0",
   "namespace": "AWS",
   "intrinsics": [

package/dist/plugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,aAAa,EAAqQ,MAAM,0BAA0B,CAAC;AAwCjU;yEACyE;AACzE,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAiBnD,eAAO,MAAM,SAAS,EAAE,aA+jCvB,CAAC"}
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,aAAa,EAAqQ,MAAM,0BAA0B,CAAC;AAwCjU;yEACyE;AACzE,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAiBnD,eAAO,MAAM,SAAS,EAAE,aAgkCvB,CAAC"}

package/dist/plugin.js

@@ -2,6 +2,7 @@ import { compositeCatalog } from "./composites/catalog.js";
 import { createRequire } from "module";
 import { awsBehaviourKinds } from "./behaviour-kinds.js";
 import { detectTemplate } from "./detect.js";
+import { awsCapabilityPack } from "./capabilities/pack.js";
 const require = createRequire(moduleSourceUrl(import.meta.url));
 import { discoverLintRules } from "@intentius/chant/lint/discover";
 import { postSynthChecks as postSynthCheckList } from "./lint/post-synth/index.js";
@@ -63,6 +64,7 @@ export const awsPlugin = {
     auditCatalog: () => awsAuditCatalog,
     // Live edge reconstruction for `chant graph --live` (#778).
     referenceCatalog: awsReferenceCatalog,
+    capabilityPack: awsCapabilityPack,
     lintRules() {
         const rulesDir = join(dirname(fileURLToPath(import.meta.url)), "lint", "rules");
         return discoverLintRules(rulesDir, import.meta.url);

package/package.json

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

package/src/capabilities/mapping.json

@@ -0,0 +1,150 @@
+{
+  "lexicon": "aws",
+  "types": "kind",
+  "refs": "cloudformation",
+  "labels": {
+    "AWS::EC2::VPC": "Vpc",
+    "AWS::EC2::NetworkInterface": "NetworkInterface",
+    "AWS::EC2::Volume": "Volume",
+    "AWS::Lambda::Function": "Function",
+    "AWS::Lambda::Url": "FunctionUrl",
+    "AWS::IAM::InstanceProfile": "InstanceProfile",
+    "AWS::IAM::Role": "Role",
+    "AWS::IAM::Policy": "Policy",
+    "AWS::IAM::ManagedPolicy": "Policy",
+    "AWS::S3::BucketPolicy": "ResourcePolicy",
+    "AWS::SQS::QueuePolicy": "ResourcePolicy",
+    "AWS::S3::Bucket": "Bucket",
+    "AWS::DynamoDB::Table": "Table",
+    "AWS::DynamoDB::GlobalTable": "Table",
+    "AWS::RDS::DBInstance": "Database",
+    "AWS::RDS::DBCluster": "Database",
+    "AWS::SecretsManager::Secret": "Secret",
+    "AWS::SQS::Queue": "Queue",
+    "AWS::EFS::FileSystem": "FileSystem",
+    "AWS::SSM::Parameter": "Parameter",
+    "AWS::ECS::Service": "Service",
+    "AWS::ECS::TaskDefinition": "TaskDefinition",
+    "AWS::RDS::DBSubnetGroup": "SubnetGroup",
+    "AWS::EC2::NatGateway": "NatGateway",
+    "AWS::ElasticLoadBalancingV2::LoadBalancer": "LoadBalancer"
+  },
+  "edges": {
+    "Instance": {
+      "IamInstanceProfile": "profile",
+      "VpcId": "vpc"
+    },
+    "LaunchTemplate": {
+      "LaunchTemplateData": {
+        "InstanceProfile": "profile"
+      }
+    },
+    "Subnet": {
+      "VpcId": "vpc"
+    },
+    "SecurityGroup": {
+      "VpcId": "vpc"
+    },
+    "NetworkInterface": {
+      "SubnetId": "subnet",
+      "GroupSet": "sg"
+    },
+    "Database": {
+      "VPCSecurityGroups": "sg",
+      "VpcSecurityGroupIds": "sg",
+      "DBSubnetGroupName": "subnetGroup"
+    },
+    "Function": {
+      "Role": "role",
+      "VpcConfig": {
+        "SecurityGroup": "sg",
+        "Subnet": "subnet"
+      }
+    },
+    "FunctionUrl": {
+      "TargetFunctionArn": "function"
+    },
+    "InstanceProfile": {
+      "Roles": "role"
+    },
+    "Policy": {
+      "Roles": "attachedTo"
+    },
+    "Role": {
+      "ManagedPolicyArns": "-attachedTo"
+    },
+    "ResourcePolicy": {
+      "Bucket": "policyOf",
+      "Queues": "policyOf"
+    },
+    "Service": {
+      "TaskDefinition": "task",
+      "NetworkConfiguration": {
+        "SecurityGroup": "sg",
+        "Subnet": "subnet"
+      }
+    },
+    "TaskDefinition": {
+      "TaskRoleArn": "role"
+    },
+    "SubnetGroup": {
+      "SubnetIds": "subnet"
+    },
+    "NatGateway": {
+      "SubnetId": "subnet"
+    },
+    "LoadBalancer": {
+      "Subnets": "subnet",
+      "SecurityGroups": "sg"
+    }
+  },
+  "attrs": {
+    "FunctionUrl": {
+      "authType": "AuthType"
+    },
+    "Role": {
+      "name": "RoleName"
+    },
+    "Bucket": {
+      "name": "BucketName",
+      "acl": "AccessControl",
+      "blockPublicPolicy": "PublicAccessBlockConfiguration.BlockPublicPolicy"
+    },
+    "Table": {
+      "name": "TableName"
+    },
+    "Database": {
+      "encrypted": "StorageEncrypted"
+    },
+    "FileSystem": {
+      "encrypted": "Encrypted"
+    },
+    "Volume": {
+      "encrypted": "Encrypted"
+    },
+    "Parameter": {
+      "paramType": "Type"
+    },
+    "Vpc": {
+      "isDefault": "IsDefault"
+    }
+  },
+  "documents": {
+    "Role": {
+      "AssumeRolePolicyDocument": "trust",
+      "Policies[].PolicyDocument": "permission"
+    },
+    "Policy": {
+      "PolicyDocument": "permission"
+    },
+    "ResourcePolicy": {
+      "PolicyDocument": "resource"
+    }
+  },
+  "tags": [
+    "Tags"
+  ],
+  "classificationTags": [
+    "data-classification"
+  ]
+}

package/src/capabilities/pack.ts

@@ -0,0 +1,9 @@
+/**
+ * The aws lexicon's capability pack (#4375): its mapping of CloudFormation
+ * kinds onto the lexicon-neutral view the capability rules read. All data;
+ * CloudFormation policy documents are JSON already, so no adapter code.
+ */
+import type { CapabilityMapping, CapabilityPack } from "@intentius/chant/capabilities/view";
+import mapping from "./mapping.json" with { type: "json" };
+
+export const awsCapabilityPack: CapabilityPack = { mapping: mapping as CapabilityMapping };

package/src/capabilities.test.ts

@@ -0,0 +1,182 @@
+/**
+ * The capability catalog over CloudFormation kinds (#4375).
+ *
+ * `testdata/capabilities-ledger/estate.ts` is the CloudFormation form of the
+ * estate chant#4361 measured the rule language on. Its hand-checked answers
+ * are identity reach 13, exfiltration 3 and blast radius 15, the same as the
+ * Terraform form's (lexicons/terraform/src/capabilities.test.ts).
+ *
+ * Three of those pairs are proved only by a reference inside a `Sub`
+ * (``Sub`${assets.Arn}/*` ``), which the graph carries as `{ $sub }` since
+ * chant#4373.
+ */
+
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { discover } from "@intentius/chant/discovery/index";
+import { buildGraphIr, type GraphIR } from "@intentius/chant/graph-ir";
+import { enrichEffectiveTopology } from "@intentius/chant/graph-effective";
+import { CapabilityEngine } from "@intentius/chant/capabilities/matcher";
+import { buildView, displayName } from "@intentius/chant/capabilities/view";
+import { lexiconSupport, resolvePacks, shippedRules, isPublic } from "@intentius/chant/capabilities/catalog";
+import { awsCapabilityPack } from "./capabilities/pack";
+
+const LEDGER = join(import.meta.dirname, "testdata", "capabilities-ledger");
+
+const engineFor = (g: GraphIR) => new CapabilityEngine(buildView(g, resolvePacks([awsCapabilityPack])), shippedRules().rules);
+
+const ir: GraphIR = buildGraphIr((await discover(LEDGER)).entities, LEDGER);
+const engine = engineFor(ir);
+
+const set = (e: CapabilityEngine, name: string, args: unknown[] = []) =>
+  [...e.set(name, e.bind(name, args as never)).keys()].map(displayName).sort();
+const pairs = (e: CapabilityEngine, name: string, args: unknown[] = []) =>
+  [...e.relation(name, e.bind(name, args as never)).out].flatMap(([a, m]) => [...m.keys()].map((b) => `${displayName(a)} ${displayName(b)}`)).sort();
+
+const REACH = [
+  "auditRole ordersTable",
+  "batchRole auditRole",
+  "batchRole ordersTable",
+  "deployRole customerData",
+  "deployRole dbSecret",
+  "reporterRole customerData",
+  "webRole assets",
+  "webRole customerData",
+  "webRole dbSecret",
+  "webRole deployRole",
+  "workerRole assets",
+  "workerRole dbSecret",
+  "workerRole ordersTable",
+];
+const EXFIL = ["reporter customerData", "webServer customerData", "webServer dbSecret"];
+const BLAST_STARTS = ["webServer", "reporter", "batch"];
+const BLAST = [
+  ...["webRole", "assets", "deployRole", "customerData", "dbSecret", "worker", "adminBox", "workerRole", "ordersTable", "customersDb"].map((x) => `webServer ${x}`),
+  "reporter reporterRole",
+  "reporter customerData",
+  "batch batchRole",
+  "batch auditRole",
+  "batch ordersTable",
+].sort();
+/** The pairs only a `Sub` reference proves (chant#4373). */
+const NEEDS_SUB = {
+  reach: ["reporterRole customerData", "webRole assets", "workerRole assets"],
+  exfil: ["reporter customerData"],
+  blast: ["reporter customerData", "webServer assets"],
+};
+const blastOf = (e: CapabilityEngine) => pairs(e, "blast").filter((p) => BLAST_STARTS.includes(p.split(" ")[0]));
+
+describe("the ledger's hand-checked answers on the CloudFormation form", () => {
+  it("identity reach 13, exfiltration 3, blast radius 15, three of them proved only by a Sub reference (chant#4373)", () => {
+    expect(pairs(engine, "reaches")).toEqual(REACH);
+    expect(pairs(engine, "exfiltrates")).toEqual(EXFIL);
+    expect(blastOf(engine)).toEqual(BLAST);
+  });
+
+  it("leaves no statement's resource unresolved", () => {
+    const unresolved = [...engine.view.nodes.values()].filter((n) => n.label === "Statement" && n.attrs.unresolved);
+    expect(unresolved.map((n) => n.id)).toEqual([]);
+  });
+
+  it("finds the Sub-only pairs through the Sub's own reference", () => {
+    for (const p of NEEDS_SUB.reach) expect(pairs(engine, "reaches")).toContain(p);
+    const ev = engine.relation("reaches").out.get("reporterRole")!.get("customerData")!;
+    expect(ev.hops.at(-1)).toMatchObject({ to: "customerData", toAttr: "Arn", edge: "resource" });
+  });
+});
+
+describe("each capability on CloudFormation kinds", () => {
+  it("internet-facing, open-ingress and internet-reachable, the open group reached only through a launch template", () => {
+    expect(set(engine, "internet-facing")).toEqual(["adminBox", "webServer"]);
+    expect(set(engine, "open-ingress", [22])).toEqual(["webServer"]);
+    expect(set(engine, "internet-reachable")).toEqual(["reporter", "webServer"]);
+  });
+
+  it("network reads the standalone SecurityGroupIngress resource as well as inline rules", () => {
+    expect(pairs(engine, "network")).toEqual([
+      "adminBox customersDb",
+      "webServer adminBox",
+      "webServer worker",
+      "worker customersDb",
+    ]);
+  });
+
+  it("stores-data, holds-secret (by data-classification tag) and encrypted-at-rest", () => {
+    expect(set(engine, "stores-data")).toEqual(["assets", "customerData", "customersDb", "dbSecret", "ordersTable"]);
+    expect(set(engine, "holds-secret")).toEqual(["customerData", "customersDb", "dbSecret"]);
+    expect(set(engine, "encrypted-at-rest")).toEqual(["assets", "customerData", "customersDb", "dbSecret", "ordersTable"]);
+  });
+
+  it("runs-as, can-assume (by reference and by ARN naming a declared role) and grants", () => {
+    expect(pairs(engine, "runs-as")).toEqual([
+      "adminBox workerRole",
+      "batch batchRole",
+      "reporter reporterRole",
+      "webServer webRole",
+      "worker workerRole",
+    ]);
+    expect(pairs(engine, "can-assume")).toEqual(["batchRole auditRole", "webRole deployRole"]);
+    expect(pairs(engine, "grants", ["dynamodb:Scan"])).toEqual(["auditRole ordersTable"]);
+  });
+
+  it("attached-to-nothing and publicly-readable hold for nothing in the ledger, and for what a small graph declares", () => {
+    expect(set(engine, "attached-to-nothing")).toEqual([]);
+    expect(set(engine, "publicly-readable")).toEqual([]);
+    const g: GraphIR = {
+      nodes: [
+        { id: "sg", kind: "AWS::EC2::SecurityGroup", lexicon: "aws", attrs: {} },
+        { id: "open", kind: "AWS::S3::Bucket", lexicon: "aws", attrs: {} },
+        { id: "openPolicy", kind: "AWS::S3::BucketPolicy", lexicon: "aws", attrs: { Bucket: { $ref: "open" }, PolicyDocument: { Statement: [{ Effect: "Allow", Principal: "*", Action: "s3:GetObject" }] } } },
+        { id: "blocked", kind: "AWS::S3::Bucket", lexicon: "aws", attrs: { PublicAccessBlockConfiguration: { BlockPublicPolicy: true } } },
+        { id: "blockedPolicy", kind: "AWS::S3::BucketPolicy", lexicon: "aws", attrs: { Bucket: { $ref: "blocked" }, PolicyDocument: { Statement: [{ Effect: "Allow", Principal: { AWS: "*" }, Action: "s3:GetObject" }] } } },
+      ] as never,
+      edges: [
+        { from: "openPolicy", to: "open", viaAttr: "Bucket" },
+        { from: "blockedPolicy", to: "blocked", viaAttr: "Bucket" },
+      ] as never,
+      groups: {},
+    };
+    const e = engineFor(g);
+    expect(set(e, "attached-to-nothing")).toEqual(["sg"]);
+    expect(set(e, "publicly-readable")).toEqual(["open"]);
+  });
+
+  it("in-default-vpc reads a live VPC's IsDefault, through the instance's VpcId or its subnet", () => {
+    const g: GraphIR = {
+      nodes: [
+        { id: "east::vpc-default", kind: "AWS::EC2::VPC", lexicon: "aws", attrs: { IsDefault: true } },
+        { id: "east::vpc-main", kind: "AWS::EC2::VPC", lexicon: "aws", attrs: { IsDefault: false } },
+        { id: "east::subnet-a", kind: "AWS::EC2::Subnet", lexicon: "aws", attrs: {} },
+        { id: "east::i-old", kind: "AWS::EC2::Instance", lexicon: "aws", attrs: {} },
+        { id: "east::i-new", kind: "AWS::EC2::Instance", lexicon: "aws", attrs: {} },
+        { id: "east::i-sub", kind: "AWS::EC2::Instance", lexicon: "aws", attrs: {} },
+      ] as never,
+      edges: [
+        { from: "east::i-old", to: "east::vpc-default", viaAttr: "VpcId" },
+        { from: "east::i-new", to: "east::vpc-main", viaAttr: "VpcId" },
+        { from: "east::i-sub", to: "east::subnet-a", viaAttr: "SubnetId" },
+        { from: "east::subnet-a", to: "east::vpc-default", viaAttr: "VpcId" },
+      ] as never,
+      groups: {},
+    };
+    expect(set(engineFor(g), "in-default-vpc")).toEqual(["i-old", "i-sub", "subnet-a"]);
+  });
+
+  it("the aws mapping supplies every capability", () => {
+    for (const rule of shippedRules().rules.filter(isPublic)) {
+      expect(lexiconSupport(rule, awsCapabilityPack.mapping, "aws"), rule.name).toBe("supported");
+    }
+  });
+});
+
+describe("the effective-topology fold over the same graph", () => {
+  it("reads the standalone ingress resource too, naming its source group", () => {
+    const enriched = enrichEffectiveTopology(ir);
+    const attrs = (id: string) => enriched.nodes.find((n) => n.id === id)!.attrs as Record<string, unknown>;
+    expect(attrs("webServer").effectiveIngress).toEqual(["tcp:443:0.0.0.0/0", "tcp:22:0.0.0.0/0"]);
+    expect(attrs("webServer").internetFacing).toBe(true);
+    expect(attrs("webServer").internetFacingVia).toBe("publicRt → igw");
+    expect(attrs("worker").effectiveIngress).toEqual(["tcp:8080:sg:webSg"]);
+    expect(attrs("worker").internetFacing).toBe(false);
+  });
+});

package/src/graph-sub-edges.test.ts

@@ -0,0 +1,101 @@
+/**
+ * A reference inside a CloudFormation `Sub` is a graph edge (chant #4373).
+ *
+ * The estate is the shape #4361 measured on: an IAM policy granting
+ * `${bucket.Arn}/*` and a database whose password is a
+ * `{{resolve:secretsmanager:${Ref(secret)}}}` reference. Before #4373 both
+ * were `{ "$intrinsic": true }` with no edge, so a search walking from the
+ * policy to a bucket found nothing.
+ */
+
+import { afterEach, describe, expect, it, vi } from "vitest";
+import type { Declarable } from "@intentius/chant/declarable";
+import { resolveAttrRefs } from "@intentius/chant/discovery/resolve";
+import { buildGraphIr, type GraphIR } from "@intentius/chant/graph-ir";
+import { applyDetail } from "@intentius/chant/graph-detail";
+import { __searchInternals, resolveKindTerms } from "@intentius/chant/cli/handlers/search";
+import { Bucket, DbInstance, Policy, Ref, Role, Secret, Sub, AWS } from "./index";
+
+const { parseQuery, matchTerm, explain } = __searchInternals;
+
+function estate(): GraphIR {
+  const assets = new Bucket({});
+  const webRole = new Role({ AssumeRolePolicyDocument: { Statement: [] } });
+  const dbSecret = new Secret({});
+  const webPolicy = new Policy({
+    PolicyName: "web",
+    Roles: [Ref(webRole)],
+    PolicyDocument: {
+      Statement: [
+        { Effect: "Allow", Action: "s3:GetObject", Resource: Sub`${assets.Arn}/*` },
+        { Effect: "Allow", Action: "logs:PutLogEvents", Resource: Sub`arn:aws:logs:${AWS.Region}:${AWS.AccountId}:*` },
+      ],
+    },
+  });
+  const customersDb = new DbInstance({
+    Engine: "postgres",
+    DBInstanceClass: "db.t3.micro",
+    MasterUserPassword: Sub`{{resolve:secretsmanager:${Ref(dbSecret)}}}`,
+  });
+  const entities = new Map<string, Declarable>([
+    ["assets", assets],
+    ["webRole", webRole],
+    ["dbSecret", dbSecret],
+    ["webPolicy", webPolicy],
+    ["customersDb", customersDb],
+  ] as Array<[string, Declarable]>);
+  resolveAttrRefs(entities);
+  return buildGraphIr(entities);
+}
+
+function search(ir: GraphIR, query: string): string[] {
+  const terms = parseQuery(query);
+  resolveKindTerms(terms, ir.nodes);
+  const byId = new Map(ir.nodes.map((n) => [n.id, n]));
+  return ir.nodes.filter((n) => terms.every((t) => matchTerm(n, t, ir, byId))).map((n) => n.id).sort();
+}
+
+describe("a Sub reference in an aws project (#4373)", () => {
+  afterEach(() => vi.restoreAllMocks());
+
+  it("is an edge from the holder through its top-level attribute, at tiers 1 to 3", () => {
+    const ir = estate();
+    for (const tier of [1, 2, 3] as const) {
+      const edges = applyDetail(ir, tier).edges.map((e) => `${e.from} -${e.viaAttr}-> ${e.to}`);
+      expect(edges).toContain("webPolicy -PolicyDocument-> assets");
+      expect(edges).toContain("customersDb -MasterUserPassword-> dbSecret");
+    }
+    const t3 = applyDetail(ir, 3).edges.find((e) => e.from === "webPolicy" && e.to === "assets");
+    expect(t3).toEqual({ from: "webPolicy", to: "assets", kind: "ref", viaAttr: "PolicyDocument", toAttr: "Arn" });
+  });
+
+  it("carries the template in a $sub envelope at --detail 3", () => {
+    const ir = applyDetail(estate(), 3);
+    const policy = ir.nodes.find((n) => n.id === "webPolicy")!;
+    const statements = (policy.attrs.PolicyDocument as { Statement: Array<{ Resource: unknown }> }).Statement;
+    expect(statements[0].Resource).toEqual({ $sub: "${assets.Arn}/*" });
+    expect(statements[1].Resource).toEqual({ $sub: "arn:aws:logs:${AWS::Region}:${AWS::AccountId}:*" });
+    const db = ir.nodes.find((n) => n.id === "customersDb")!;
+    expect(db.attrs.MasterUserPassword).toEqual({ $sub: "{{resolve:secretsmanager:${dbSecret}}}" });
+  });
+
+  it("a pseudo-parameter-only Sub adds no edge", () => {
+    const fromPolicy = estate().edges.filter((e) => e.from === "webPolicy").map((e) => e.to).sort();
+    expect(fromPolicy).toEqual(["assets", "webRole"]);
+  });
+
+  it('search "->*kind:AWS::S3::Bucket" follows the edge, and --explain prints it', () => {
+    const ir = estate();
+    expect(search(ir, "->*kind:AWS::S3::Bucket")).toEqual(["webPolicy"]);
+
+    const lines: string[] = [];
+    vi.spyOn(console, "log").mockImplementation((line: unknown) => void lines.push(String(line)));
+    const query = "->*kind:AWS::S3::Bucket";
+    const terms = parseQuery(query);
+    resolveKindTerms(terms, ir.nodes);
+    const byId = new Map(ir.nodes.map((n) => [n.id, n]));
+    const matches = ir.nodes.filter((n) => terms.every((t) => matchTerm(n, t, ir, byId)));
+    explain(terms, matches, ir, byId, query);
+    expect(lines.join("\n")).toContain("path webPolicy.PolicyDocument -> assets");
+  });
+});

package/src/plugin.ts

@@ -2,6 +2,7 @@ import { compositeCatalog } from "./composites/catalog";
 import { createRequire } from "module";
 import { awsBehaviourKinds } from "./behaviour-kinds";
 import { detectTemplate } from "./detect";
+import { awsCapabilityPack } from "./capabilities/pack";
 import type { LexiconPlugin, IntrinsicDef, ObservationResult, DeepObservationResult, DependencyObservation, DescribeIdentityOptions, DescribeIdentityResult, DisruptionQuery, DisruptionVerdict, ResourceMetadata, ExportedTemplate, ResourceSelector, InitTemplateSet, StackStatusObservation } from "@intentius/chant/lexicon";
 const require = createRequire(moduleSourceUrl(import.meta.url));
 import type { LintRule } from "@intentius/chant/lint/rule";
@@ -79,6 +80,7 @@ export const awsPlugin: LexiconPlugin = {
   auditCatalog: () => awsAuditCatalog,
   // Live edge reconstruction for `chant graph --live` (#778).
   referenceCatalog: awsReferenceCatalog,
+  capabilityPack: awsCapabilityPack,
 
   lintRules(): LintRule[] {
     const rulesDir = join(dirname(fileURLToPath(import.meta.url)), "lint", "rules");

package/src/testdata/capabilities-ledger/estate.ts

@@ -0,0 +1,161 @@
+// "ledger": the CloudFormation form of the estate chant#4361 measured the rule language on (#4375).
+import {
+  Bucket, DbInstance, EC2Route, EC2SecurityGroupIngress, Function, Instance, InstanceProfile,
+  InternetGateway, LaunchTemplate, ManagedPolicy, Policy, Role, RouteTable, S3BucketPolicy, Secret,
+  SecurityGroup, Subnet, SubnetRouteTableAssociation, Table, Url, Vpc, VPCGatewayAttachment, Ref, Sub,
+} from "@intentius/chant-lexicon-aws";
+
+const AMI = "ami-0f3f13f145e66a0a3";
+const restricted = [{ Key: "data-classification", Value: "restricted" }];
+const trustService = (svc: string) => ({
+  Version: "2012-10-17",
+  Statement: [{ Effect: "Allow", Principal: { Service: svc }, Action: "sts:AssumeRole" }],
+});
+
+// network
+export const vpc = new Vpc({ CidrBlock: "10.0.0.0/16" });
+export const publicSubnet = new Subnet({ VpcId: vpc.VpcId, CidrBlock: "10.0.0.0/24" });
+export const privateSubnet = new Subnet({ VpcId: vpc.VpcId, CidrBlock: "10.0.1.0/24" });
+export const igw = new InternetGateway({});
+export const igwAttachment = new VPCGatewayAttachment({ VpcId: vpc.VpcId, InternetGatewayId: igw.InternetGatewayId });
+export const publicRt = new RouteTable({ VpcId: vpc.VpcId });
+export const privateRt = new RouteTable({ VpcId: vpc.VpcId });
+export const publicDefault = new EC2Route({ RouteTableId: publicRt.RouteTableId, DestinationCidrBlock: "0.0.0.0/0", GatewayId: igw.InternetGatewayId });
+export const publicAssoc = new SubnetRouteTableAssociation({ RouteTableId: publicRt.RouteTableId, SubnetId: publicSubnet.SubnetId });
+export const privateAssoc = new SubnetRouteTableAssociation({ RouteTableId: privateRt.RouteTableId, SubnetId: privateSubnet.SubnetId });
+
+export const webSg = new SecurityGroup({
+  GroupDescription: "web", VpcId: vpc.VpcId,
+  SecurityGroupIngress: [
+    { IpProtocol: "tcp", FromPort: 443, ToPort: 443, CidrIp: "0.0.0.0/0" },
+    { IpProtocol: "tcp", FromPort: 22, ToPort: 22, CidrIp: "0.0.0.0/0" },
+  ],
+});
+export const appSg = new SecurityGroup({ GroupDescription: "app", VpcId: vpc.VpcId });
+export const appFromWeb = new EC2SecurityGroupIngress({
+  GroupId: appSg.GroupId, IpProtocol: "tcp", FromPort: 8080, ToPort: 8080, SourceSecurityGroupId: webSg.GroupId,
+});
+export const dbSg = new SecurityGroup({
+  GroupDescription: "db", VpcId: vpc.VpcId,
+  SecurityGroupIngress: [{ IpProtocol: "tcp", FromPort: 5432, ToPort: 5432, SourceSecurityGroupId: appSg.GroupId }],
+});
+
+// data
+export const assets = new Bucket({ PublicAccessBlockConfiguration: { BlockPublicAcls: true, BlockPublicPolicy: true, IgnorePublicAcls: true, RestrictPublicBuckets: true } });
+export const customerData = new Bucket({ Tags: restricted, PublicAccessBlockConfiguration: { BlockPublicAcls: true, BlockPublicPolicy: true, IgnorePublicAcls: true, RestrictPublicBuckets: true } });
+export const ordersTable = new Table({
+  KeySchema: [{ AttributeName: "id", KeyType: "HASH" }],
+  AttributeDefinitions: [{ AttributeName: "id", AttributeType: "S" }],
+  BillingMode: "PAY_PER_REQUEST",
+});
+export const dbSecret = new Secret({ GenerateSecretString: { PasswordLength: 32 } });
+export const customersDb = new DbInstance({
+  Engine: "postgres", DBInstanceClass: "db.t3.micro", AllocatedStorage: "20",
+  MasterUsername: "ledger", MasterUserPassword: Sub`{{resolve:secretsmanager:${Ref(dbSecret)}}}`,
+  VPCSecurityGroups: [dbSg.GroupId], PubliclyAccessible: false, Tags: restricted, StorageEncrypted: true, BackupRetentionPeriod: 7,
+});
+
+// identity
+export const webRole = new Role({ AssumeRolePolicyDocument: trustService("ec2.amazonaws.com") });
+export const deployRole = new Role({
+  AssumeRolePolicyDocument: {
+    Version: "2012-10-17",
+    Statement: [{ Effect: "Allow", Principal: { AWS: webRole.Arn }, Action: "sts:AssumeRole" }],
+  },
+});
+export const webPolicy = new Policy({
+  PolicyName: "web", Roles: [Ref(webRole)],
+  PolicyDocument: {
+    Version: "2012-10-17",
+    Statement: [
+      { Effect: "Allow", Action: "s3:GetObject", Resource: Sub`${assets.Arn}/*` },
+      { Effect: "Allow", Action: "sts:AssumeRole", Resource: deployRole.Arn },
+    ],
+  },
+});
+export const deployPolicy = new Policy({
+  PolicyName: "deploy", Roles: [Ref(deployRole)],
+  PolicyDocument: {
+    Version: "2012-10-17",
+    Statement: [
+      { Effect: "Allow", Action: "s3:*", Resource: [customerData.Arn, Sub`${customerData.Arn}/*`] },
+      { Effect: "Allow", Action: "secretsmanager:GetSecretValue", Resource: Ref(dbSecret) },
+    ],
+  },
+});
+export const workerRole = new Role({
+  AssumeRolePolicyDocument: trustService("ec2.amazonaws.com"),
+  Policies: [{
+    PolicyName: "worker",
+    PolicyDocument: {
+      Version: "2012-10-17",
+      Statement: [
+        { Effect: "Allow", Action: "secretsmanager:GetSecretValue", Resource: Ref(dbSecret) },
+        { Effect: "Allow", Action: ["dynamodb:GetItem", "dynamodb:PutItem"], Resource: ordersTable.Arn },
+      ],
+    },
+  }],
+});
+export const reporterRole = new Role({ AssumeRolePolicyDocument: trustService("lambda.amazonaws.com") });
+export const reportRead = new ManagedPolicy({
+  Roles: [Ref(reporterRole)],
+  PolicyDocument: {
+    Version: "2012-10-17",
+    Statement: [
+      { Effect: "Allow", Action: "s3:GetObject", Resource: Sub`${customerData.Arn}/*` },
+      { Effect: "Allow", Action: "logs:*", Resource: "*" },
+    ],
+  },
+});
+export const batchRole = new Role({
+  AssumeRolePolicyDocument: trustService("lambda.amazonaws.com"),
+  Policies: [{
+    PolicyName: "batch",
+    PolicyDocument: { Version: "2012-10-17", Statement: [{ Effect: "Allow", Action: "sts:AssumeRole", Resource: "arn:aws:iam::123456789012:role/audit" }] },
+  }],
+});
+export const auditRole = new Role({
+  RoleName: "audit",
+  AssumeRolePolicyDocument: {
+    Version: "2012-10-17",
+    Statement: [{ Effect: "Allow", Principal: { AWS: batchRole.Arn }, Action: "sts:AssumeRole" }],
+  },
+  Policies: [{
+    PolicyName: "audit",
+    PolicyDocument: { Version: "2012-10-17", Statement: [{ Effect: "Allow", Action: "dynamodb:Scan", Resource: ordersTable.Arn }] },
+  }],
+});
+export const assetsPolicy = new S3BucketPolicy({
+  Bucket: Ref(assets),
+  PolicyDocument: {
+    Version: "2012-10-17",
+    Statement: [{ Effect: "Allow", Principal: { AWS: workerRole.Arn }, Action: "s3:GetObject", Resource: Sub`${assets.Arn}/*` }],
+  },
+});
+
+// compute
+export const webProfile = new InstanceProfile({ Roles: [Ref(webRole)] });
+export const workerProfile = new InstanceProfile({ Roles: [Ref(workerRole)] });
+export const webTemplate = new LaunchTemplate({
+  LaunchTemplateData: { InstanceType: "t3.micro", ImageId: AMI, SecurityGroupIds: [webSg.GroupId] },
+});
+export const webServer = new Instance({
+  LaunchTemplate: { LaunchTemplateId: webTemplate.LaunchTemplateId, Version: "1" },
+  SubnetId: publicSubnet.SubnetId, IamInstanceProfile: Ref(webProfile),
+});
+export const worker = new Instance({
+  ImageId: AMI, InstanceType: "t3.micro", SubnetId: privateSubnet.SubnetId,
+  SecurityGroupIds: [appSg.GroupId], IamInstanceProfile: Ref(workerProfile),
+});
+// in a public subnet, but nothing on the internet is allowed in
+export const adminBox = new Instance({
+  ImageId: AMI, InstanceType: "t3.micro", SubnetId: publicSubnet.SubnetId,
+  SecurityGroupIds: [appSg.GroupId], IamInstanceProfile: Ref(workerProfile),
+});
+export const reporter = new Function({
+  Runtime: "nodejs22.x", Handler: "index.handler", Role: reporterRole.Arn, Code: { ZipFile: "exports.handler=async()=>1" },
+});
+export const reporterUrl = new Url({ TargetFunctionArn: reporter.Arn, AuthType: "NONE" });
+export const batch = new Function({
+  Runtime: "nodejs22.x", Handler: "index.handler", Role: batchRole.Arn, Code: { ZipFile: "exports.handler=async()=>1" },
+});