@intentius/chant-lexicon-aws 0.124.31 → 0.124.33

package/dist/deep-topology.js

@@ -0,0 +1,226 @@
+/**
+ * Deep-read sources for the EC2 topology types (#1269).
+ *
+ * chant's distinguishing answers are folds over topology: `internetFacing`
+ * resolves subnet -> route table -> internet gateway, `effectiveIngress`
+ * resolves rules across attached security groups, and the default-VPC
+ * classification (`defaults.ts`) reads the provider's own markers. The inputs
+ * to all of them are the types this file covers — with only the original four
+ * kinds readable, a deep snapshot of an EC2 estate carried almost no
+ * properties, and a snapshot-backed query could answer identity questions but
+ * not a single fold question.
+ *
+ * Two sources, chosen per type:
+ *
+ * - The container types (VPC, subnet, route table, internet gateway) read
+ *   through the EC2 describes. The fold facts live there and nowhere else:
+ *   `IsDefault`, `DefaultForAz` and a subnet's live `MapPublicIpOnLaunch` are
+ *   not part of the CloudFormation resource model, so Cloud Control cannot
+ *   report them. The describes are also bulk (one call per type for the whole
+ *   stack) and are implemented by the emulators that do not serve Cloud
+ *   Control's `GetResource`.
+ *
+ * - The join types (route, association, gateway attachment) and the two whose
+ *   describes do not fit a flat bulk join (instance rows nest inside
+ *   reservations; launch-template data lives in a separate versions call) read
+ *   through Cloud Control, which returns their model in the declared side's
+ *   own shape.
+ *
+ * Each type carries its normalization entries alongside (#1269's note: adding
+ * a type without them trades a hole for a false positive, which is worse).
+ * They are merged into the tables in `deep-observe.ts`.
+ */
+/**
+ * `describe-vpcs` -> the `AWS::EC2::VPC` resource model, plus `IsDefault`.
+ *
+ * `IsDefault` is the provider's own marker for the VPC nobody wrote — the fact
+ * the default classification reads — and it exists only on this surface.
+ * Carried even though the model does not name it; the diff subtracts it as a
+ * service default (`false`, gated on source silence) so a CloudFormation-made
+ * VPC does not report it as undeclared drift.
+ */
+export function vpcToModel(row) {
+    return {
+        // The schema's readOnlyProperties prune the id after the ownership check.
+        ...(typeof row.VpcId === "string" ? { VpcId: row.VpcId } : {}),
+        ...(typeof row.CidrBlock === "string" ? { CidrBlock: row.CidrBlock } : {}),
+        ...(typeof row.InstanceTenancy === "string" ? { InstanceTenancy: row.InstanceTenancy } : {}),
+        ...(typeof row.IsDefault === "boolean" ? { IsDefault: row.IsDefault } : {}),
+        ...nonEmptyTags(row),
+    };
+}
+/**
+ * `describe-subnets` -> the `AWS::EC2::Subnet` resource model, plus
+ * `DefaultForAz`.
+ *
+ * `MapPublicIpOnLaunch` is half of `internetFacing`; `DefaultForAz` is the
+ * provider's default-subnet marker, off the model for the same reason as a
+ * VPC's `IsDefault` and handled the same way.
+ */
+export function subnetToModel(row) {
+    return {
+        ...(typeof row.SubnetId === "string" ? { SubnetId: row.SubnetId } : {}),
+        ...(typeof row.VpcId === "string" ? { VpcId: row.VpcId } : {}),
+        ...(typeof row.CidrBlock === "string" ? { CidrBlock: row.CidrBlock } : {}),
+        ...(typeof row.AvailabilityZone === "string" ? { AvailabilityZone: row.AvailabilityZone } : {}),
+        ...(typeof row.AvailabilityZoneId === "string" ? { AvailabilityZoneId: row.AvailabilityZoneId } : {}),
+        ...(typeof row.MapPublicIpOnLaunch === "boolean" ? { MapPublicIpOnLaunch: row.MapPublicIpOnLaunch } : {}),
+        ...(typeof row.AssignIpv6AddressOnCreation === "boolean"
+            ? { AssignIpv6AddressOnCreation: row.AssignIpv6AddressOnCreation }
+            : {}),
+        ...(typeof row.EnableDns64 === "boolean" ? { EnableDns64: row.EnableDns64 } : {}),
+        ...(typeof row.Ipv6Native === "boolean" ? { Ipv6Native: row.Ipv6Native } : {}),
+        ...(typeof row.DefaultForAz === "boolean" ? { DefaultForAz: row.DefaultForAz } : {}),
+        ...nonEmptyTags(row),
+    };
+}
+/**
+ * `describe-route-tables` -> the `AWS::EC2::RouteTable` resource model.
+ *
+ * The row also carries `Routes` and `Associations`, and this mapping drops
+ * them on purpose: a template declares each route as its own
+ * `AWS::EC2::Route` and each association as its own
+ * `AWS::EC2::SubnetRouteTableAssociation`, both covered below, so carrying
+ * them here would report every declared route twice — once as an undeclared
+ * array on the table and once through its own resource.
+ */
+export function routeTableToModel(row) {
+    return {
+        ...(typeof row.RouteTableId === "string" ? { RouteTableId: row.RouteTableId } : {}),
+        ...(typeof row.VpcId === "string" ? { VpcId: row.VpcId } : {}),
+        ...nonEmptyTags(row),
+    };
+}
+/** `describe-internet-gateways` -> the `AWS::EC2::InternetGateway` model, which is tags and nothing else. */
+export function internetGatewayToModel(row) {
+    return {
+        ...(typeof row.InternetGatewayId === "string" ? { InternetGatewayId: row.InternetGatewayId } : {}),
+        ...nonEmptyTags(row),
+    };
+}
+/**
+ * An empty tag set is the absence of tags, not a value. EC2 always sends the
+ * key, so carrying it through reports `Tags: <undeclared> -> []` on every
+ * untagged resource — agreement rendered as drift. Same rule as the
+ * security-group mapping.
+ */
+function nonEmptyTags(row) {
+    return Array.isArray(row.Tags) && row.Tags.length > 0 ? { Tags: row.Tags } : {};
+}
+/**
+ * The topology types' entries for `DEEP_SOURCES`.
+ *
+ * The routing-chain joins are addressed by their physical id — for a
+ * registry-backed type CloudFormation's physical id *is* the Cloud Control
+ * identifier (`rtb-…|0.0.0.0/0` for a route) — so Cloud Control's
+ * one-get-per-resource shape fits them exactly and returns the declared
+ * model's own field names.
+ */
+export const EC2_TOPOLOGY_SOURCES = {
+    "AWS::EC2::VPC": {
+        via: "ec2",
+        argv: ["ec2", "describe-vpcs"],
+        idFlag: "--vpc-ids",
+        key: "Vpcs",
+        id: "VpcId",
+        toModel: vpcToModel,
+    },
+    "AWS::EC2::Subnet": {
+        via: "ec2",
+        argv: ["ec2", "describe-subnets"],
+        idFlag: "--subnet-ids",
+        key: "Subnets",
+        id: "SubnetId",
+        toModel: subnetToModel,
+    },
+    "AWS::EC2::RouteTable": {
+        via: "ec2",
+        argv: ["ec2", "describe-route-tables"],
+        idFlag: "--route-table-ids",
+        key: "RouteTables",
+        id: "RouteTableId",
+        toModel: routeTableToModel,
+    },
+    "AWS::EC2::InternetGateway": {
+        via: "ec2",
+        argv: ["ec2", "describe-internet-gateways"],
+        idFlag: "--internet-gateway-ids",
+        key: "InternetGateways",
+        id: "InternetGatewayId",
+        toModel: internetGatewayToModel,
+    },
+    // The `0.0.0.0/0` -> igw edge `internetFacing` walks.
+    "AWS::EC2::Route": { via: "cloud-control" },
+    // Subnet -> route table.
+    "AWS::EC2::SubnetRouteTableAssociation": { via: "cloud-control" },
+    // Igw -> VPC.
+    "AWS::EC2::VPCGatewayAttachment": { via: "cloud-control" },
+    // Subnet, security groups, launch template — the instance end of both folds.
+    "AWS::EC2::Instance": { via: "cloud-control" },
+    // The indirect security-group hop `effectiveIngress` resolves through.
+    "AWS::EC2::LaunchTemplate": { via: "cloud-control" },
+};
+/**
+ * Service defaults for the topology types, merged into
+ * `AWS_SERVICE_DEFAULTS`. Subtracted on the live side only where source never
+ * declared the property — which is how the fold facts (`IsDefault`,
+ * `DefaultForAz`, a live `MapPublicIpOnLaunch`) stay in the snapshot for a
+ * query to read while never surfacing as drift on a resource CloudFormation
+ * itself created.
+ */
+export const EC2_TOPOLOGY_SERVICE_DEFAULTS = {
+    "AWS::EC2::VPC": {
+        InstanceTenancy: "default",
+        IsDefault: false,
+    },
+    "AWS::EC2::Subnet": {
+        MapPublicIpOnLaunch: false,
+        AssignIpv6AddressOnCreation: false,
+        EnableDns64: false,
+        Ipv6Native: false,
+        DefaultForAz: false,
+    },
+    "AWS::EC2::Instance": {
+        Tenancy: "default",
+        Monitoring: false,
+        EbsOptimized: false,
+        SourceDestCheck: true,
+        DisableApiTermination: false,
+    },
+};
+/**
+ * Values the service picks when the template does not supply one, merged into
+ * `AWS_GENERATED_NAMES`. A subnet that names no availability zone gets one
+ * assigned — a different one is real placement drift only when the template
+ * had an opinion, which is exactly the counterpart gate.
+ */
+export const EC2_TOPOLOGY_GENERATED_NAMES = {
+    "AWS::EC2::Subnet": new Set(["AvailabilityZone", "AvailabilityZoneId"]),
+    "AWS::EC2::Instance": new Set(["AvailabilityZone"]),
+};
+/**
+ * Declared properties a type's source cannot see (#1269).
+ *
+ * `describe-vpcs` does not return the DNS attributes — they live behind
+ * `describe-vpc-attribute` — and neither describe returns the IPAM inputs,
+ * which are consumed at creation. A declared value for one of these has
+ * nothing live to stand against, so the diff would report `value -> <absent>`
+ * on every clean apply: a blind spot rendered as drift. Pruned on the
+ * declared side, and only where the live tree is silent, so a source that
+ * does report the field (Cloud Control, some day) is still compared.
+ */
+export const AWS_DEEP_BLIND_SPOTS = {
+    "AWS::EC2::VPC": new Set([
+        "EnableDnsSupport",
+        "EnableDnsHostnames",
+        "Ipv4IpamPoolId",
+        "Ipv4NetmaskLength",
+    ]),
+    "AWS::EC2::Subnet": new Set([
+        "Ipv6CidrBlock",
+        "Ipv4IpamPoolId",
+        "Ipv4NetmaskLength",
+        "Ipv6IpamPoolId",
+        "Ipv6NetmaskLength",
+    ]),
+};

package/dist/default-tags.js

@@ -0,0 +1,50 @@
+/**
+ * Default Tags — declares project-wide tags for all taggable resources.
+ *
+ * When a project exports a `defaultTags(...)` declaration, the serializer
+ * automatically injects those tags into every taggable resource at synthesis
+ * time. Explicit tags on individual resources take precedence.
+ */
+import { DECLARABLE_MARKER } from "@intentius/chant/declarable";
+/**
+ * Marker symbol for default tags identification.
+ */
+export const DEFAULT_TAGS_MARKER = Symbol.for("chant.aws.defaultTags");
+/**
+ * Type guard for DefaultTags.
+ */
+export function isDefaultTags(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        DEFAULT_TAGS_MARKER in value &&
+        value[DEFAULT_TAGS_MARKER] === true);
+}
+/**
+ * Declare project-wide default tags for all taggable resources.
+ *
+ * Tags are injected at synthesis time into every resource that supports
+ * tagging (per the CloudFormation Registry metadata). If a resource has
+ * an explicit Tag with the same Key, the explicit value wins.
+ *
+ * @param tags - Array of { Key, Value } tag entries
+ * @returns A DefaultTags Declarable
+ *
+ * @example
+ * ```ts
+ * import { defaultTags, Sub, AWS } from "@intentius/chant-lexicon-aws";
+ *
+ * export const tags = defaultTags([
+ *   { Key: "Project", Value: "my-app" },
+ *   { Key: "Environment", Value: Sub`${AWS.StackName}` },
+ * ]);
+ * ```
+ */
+export function defaultTags(tags) {
+    return {
+        [DEFAULT_TAGS_MARKER]: true,
+        [DECLARABLE_MARKER]: true,
+        lexicon: "aws",
+        entityType: "chant:aws:defaultTags",
+        tags,
+    };
+}

package/dist/defaults.js

@@ -0,0 +1,85 @@
+/**
+ * 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.
+ */
+/**
+ * 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 = {
+    "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?.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) {
+    return kind in PROVIDER_DEFAULT;
+}
+/** The kinds whose provider-default status this lexicon can report. */
+export const DEFAULT_AWARE_KINDS = 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) {
+    const stamped = {};
+    for (const [name, meta] of Object.entries(resources)) {
+        const test = PROVIDER_DEFAULT[meta.type];
+        const attrs = (meta.attributes ?? {});
+        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/dist/dependencies.js

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

package/dist/detect.js

@@ -0,0 +1,21 @@
+/** Edge-safe template detection for aws (CloudFormation) — see #426. */
+export function detectTemplate(data) {
+    if (typeof data !== "object" || data === null)
+        return false;
+    const obj = data;
+    // CloudFormation has AWSTemplateFormatVersion
+    if (obj.AWSTemplateFormatVersion !== undefined)
+        return true;
+    // Or Resources with AWS::* types
+    if (typeof obj.Resources === "object" && obj.Resources !== null) {
+        for (const resource of Object.values(obj.Resources)) {
+            if (typeof resource === "object" && resource !== null) {
+                const type = resource.Type;
+                if (typeof type === "string" && type.startsWith("AWS::")) {
+                    return true;
+                }
+            }
+        }
+    }
+    return false;
+}

package/dist/disruption.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"disruption.d.ts","sourceRoot":"","sources":["../src/disruption.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAInF,kFAAkF;AAClF,MAAM,WAAW,cAAc;IAC7B,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,oGAAoG;IACpG,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,qBAAqB,CAAC,EAAE,MAAM,EAAE,CAAC;IACjC,mBAAmB,CAAC,EAAE,oBAAoB,GAAG,oBAAoB,CAAC;CACnE;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,eAAe,EACtB,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,GACjC,iBAAiB,CAuDnB;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE;IACrC,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,eAAe,EAAE,CAAC;CAC5B,GAAG,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAOpC"}
+{"version":3,"file":"disruption.d.ts","sourceRoot":"","sources":["../src/disruption.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAInF,kFAAkF;AAClF,MAAM,WAAW,cAAc;IAC7B,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,oGAAoG;IACpG,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,qBAAqB,CAAC,EAAE,MAAM,EAAE,CAAC;IACjC,mBAAmB,CAAC,EAAE,oBAAoB,GAAG,oBAAoB,CAAC;CACnE;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,eAAe,EACtB,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,GACjC,iBAAiB,CAuDnB;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE;IACrC,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,eAAe,EAAE,CAAC;CAC5B,GAAG,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAOpC"}