@intentius/chant-lexicon-aws 0.1.1 → 0.1.4

package/src/index.ts

@@ -79,12 +79,14 @@ export {
   LambdaSqs, LambdaEventBridge, LambdaDynamoDB, LambdaS3, LambdaSns,
   VpcDefault, FargateAlb, AlbShared, FargateService, RdsInstance, RdsPostgres,
   EfsWithAccessPoint,
+  Ec2InstanceRole, MinimalVpc,
 } from "./composites/index";
 export type {
   LambdaFunctionProps, LambdaApiProps, ScheduledLambdaProps,
   LambdaSqsProps, LambdaEventBridgeProps, LambdaDynamoDBProps, LambdaS3Props, LambdaSnsProps,
   VpcDefaultProps, FargateAlbProps, AlbSharedProps, FargateServiceProps, RdsInstanceProps, RdsPostgresProps,
   EfsWithAccessPointProps,
+  Ec2InstanceRoleProps, MinimalVpcProps,
 } from "./composites/index";
 
 // Code generation pipeline

package/src/lint/post-synth/waw032.test.ts

@@ -0,0 +1,83 @@
+import { describe, test, expect } from "bun:test";
+import { createPostSynthContext } from "@intentius/chant-test-utils";
+import { waw032, checkEfsTransitEncryption } from "./waw032";
+
+function makeCtx(template: object) {
+  return createPostSynthContext({ aws: template });
+}
+
+describe("WAW032: EFS Transit Encryption Disabled", () => {
+  test("check metadata", () => {
+    expect(waw032.id).toBe("WAW032");
+    expect(waw032.description).toContain("transit encryption");
+  });
+
+  test("flags task with DISABLED transit encryption", () => {
+    const ctx = makeCtx({
+      Resources: {
+        MyTask: {
+          Type: "AWS::ECS::TaskDefinition",
+          Properties: {
+            Volumes: [
+              {
+                Name: "solr-data",
+                EFSVolumeConfiguration: {
+                  FileSystemId: "fs-abc123",
+                  TransitEncryption: "DISABLED",
+                },
+              },
+            ],
+          },
+        },
+      },
+    });
+    const diags = checkEfsTransitEncryption(ctx);
+    expect(diags).toHaveLength(1);
+    expect(diags[0].checkId).toBe("WAW032");
+    expect(diags[0].severity).toBe("warning");
+    expect(diags[0].entity).toBe("MyTask");
+  });
+
+  test("no diagnostic when transit encryption is ENABLED", () => {
+    const ctx = makeCtx({
+      Resources: {
+        MyTask: {
+          Type: "AWS::ECS::TaskDefinition",
+          Properties: {
+            Volumes: [
+              {
+                Name: "solr-data",
+                EFSVolumeConfiguration: {
+                  FileSystemId: "fs-abc123",
+                  TransitEncryption: "ENABLED",
+                },
+              },
+            ],
+          },
+        },
+      },
+    });
+    expect(checkEfsTransitEncryption(ctx)).toHaveLength(0);
+  });
+
+  test("no diagnostic when no EFS volumes", () => {
+    const ctx = makeCtx({
+      Resources: {
+        MyTask: {
+          Type: "AWS::ECS::TaskDefinition",
+          Properties: { Volumes: [] },
+        },
+      },
+    });
+    expect(checkEfsTransitEncryption(ctx)).toHaveLength(0);
+  });
+
+  test("ignores non-task resources", () => {
+    const ctx = makeCtx({
+      Resources: {
+        MyBucket: { Type: "AWS::S3::Bucket", Properties: {} },
+      },
+    });
+    expect(checkEfsTransitEncryption(ctx)).toHaveLength(0);
+  });
+});

package/src/lint/post-synth/waw032.ts

@@ -0,0 +1,52 @@
+/**
+ * WAW032: EFS Transit Encryption Disabled
+ *
+ * Flags EFS volume configurations on Fargate task definitions where transit
+ * encryption has been explicitly disabled. FargateService defaults to ENABLED;
+ * this rule catches intentional opt-outs.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { parseCFTemplate } from "./cf-refs";
+
+export function checkEfsTransitEncryption(ctx: PostSynthContext): PostSynthDiagnostic[] {
+  const diagnostics: PostSynthDiagnostic[] = [];
+
+  for (const [_lexicon, output] of ctx.outputs) {
+    const template = parseCFTemplate(output);
+    if (!template?.Resources) continue;
+
+    for (const [logicalId, resource] of Object.entries(template.Resources)) {
+      if (resource.Type !== "AWS::ECS::TaskDefinition") continue;
+
+      const volumes = resource.Properties?.Volumes;
+      if (!Array.isArray(volumes)) continue;
+
+      for (const volume of volumes) {
+        const efsConfig = volume?.EFSVolumeConfiguration;
+        if (!efsConfig) continue;
+
+        if (efsConfig.TransitEncryption === "DISABLED") {
+          diagnostics.push({
+            checkId: "WAW032",
+            severity: "warning",
+            message: `EFS volume "${volume.Name ?? "unnamed"}" in task "${logicalId}" has transit encryption disabled — set TransitEncryption: ENABLED to protect data in transit`,
+            entity: logicalId,
+            lexicon: "aws",
+          });
+        }
+      }
+    }
+  }
+
+  return diagnostics;
+}
+
+export const waw032: PostSynthCheck = {
+  id: "WAW032",
+  description: "EFS volume on Fargate task has transit encryption disabled",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    return checkEfsTransitEncryption(ctx);
+  },
+};

package/src/lint/post-synth/waw033.test.ts

@@ -0,0 +1,68 @@
+import { describe, test, expect } from "bun:test";
+import { createPostSynthContext } from "@intentius/chant-test-utils";
+import { waw033, checkSolrHeapRatio } from "./waw033";
+
+function makeTask(memory: string, image: string, solrHeap?: string) {
+  return createPostSynthContext({
+    aws: {
+      Resources: {
+        SolrTask: {
+          Type: "AWS::ECS::TaskDefinition",
+          Properties: {
+            Memory: memory,
+            ContainerDefinitions: [
+              {
+                Name: "app",
+                Image: image,
+                ...(solrHeap && {
+                  Environment: [{ Name: "SOLR_HEAP", Value: solrHeap }],
+                }),
+              },
+            ],
+          },
+        },
+      },
+    },
+  });
+}
+
+describe("WAW033: Solr Heap Ratio", () => {
+  test("check metadata", () => {
+    expect(waw033.id).toBe("WAW033");
+    expect(waw033.description).toContain("SOLR_HEAP");
+  });
+
+  test("flags heap > 50% of task memory (string MB)", () => {
+    const diags = checkSolrHeapRatio(makeTask("2048", "solr:9", "1500m"));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].checkId).toBe("WAW033");
+    expect(diags[0].severity).toBe("error");
+  });
+
+  test("flags heap > 50% specified in gigabytes", () => {
+    // 2g = 2048MB, task is 2048MB — 2048 > 1024 (50%)
+    const diags = checkSolrHeapRatio(makeTask("2048", "solr:9", "2g"));
+    expect(diags).toHaveLength(1);
+  });
+
+  test("no diagnostic when heap is within limit", () => {
+    // 900m < 50% of 2048 (1024)
+    const diags = checkSolrHeapRatio(makeTask("2048", "solr:9", "900m"));
+    expect(diags).toHaveLength(0);
+  });
+
+  test("no diagnostic when SOLR_HEAP not set", () => {
+    const diags = checkSolrHeapRatio(makeTask("2048", "solr:9"));
+    expect(diags).toHaveLength(0);
+  });
+
+  test("no diagnostic for non-solr image", () => {
+    const diags = checkSolrHeapRatio(makeTask("2048", "nginx:latest", "1500m"));
+    expect(diags).toHaveLength(0);
+  });
+
+  test("detects solr image case-insensitively", () => {
+    const diags = checkSolrHeapRatio(makeTask("2048", "myrepo/Solr-Custom:9.7", "1500m"));
+    expect(diags).toHaveLength(1);
+  });
+});

package/src/lint/post-synth/waw033.ts

@@ -0,0 +1,86 @@
+/**
+ * WAW033: Solr Heap Exceeds 50% of Container Memory
+ *
+ * When SOLR_HEAP is set on a Fargate task running a Solr image, validates that
+ * the heap does not exceed 50% of the task's allocated memory. Exceeding this
+ * leaves insufficient headroom for the OS file cache that Lucene MMap relies on,
+ * causing the OOM killer to terminate the container.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { parseCFTemplate } from "./cf-refs";
+
+/** Parse heap strings like "4g", "2048m", "2048" → megabytes */
+function parseHeapMb(value: string): number | null {
+  const lower = value.trim().toLowerCase();
+  const gMatch = lower.match(/^(\d+(?:\.\d+)?)g$/);
+  if (gMatch) return Math.round(parseFloat(gMatch[1]) * 1024);
+  const mMatch = lower.match(/^(\d+(?:\.\d+)?)m?$/);
+  if (mMatch) return Math.round(parseFloat(mMatch[1]));
+  return null;
+}
+
+function isSolrImage(image: unknown): boolean {
+  return typeof image === "string" && image.toLowerCase().includes("solr");
+}
+
+export function checkSolrHeapRatio(ctx: PostSynthContext): PostSynthDiagnostic[] {
+  const diagnostics: PostSynthDiagnostic[] = [];
+
+  for (const [_lexicon, output] of ctx.outputs) {
+    const template = parseCFTemplate(output);
+    if (!template?.Resources) continue;
+
+    for (const [logicalId, resource] of Object.entries(template.Resources)) {
+      if (resource.Type !== "AWS::ECS::TaskDefinition") continue;
+
+      const props = resource.Properties ?? {};
+      if (typeof props.Memory !== "string") continue;
+      const taskMemoryMb = parseInt(props.Memory);
+      if (!taskMemoryMb) continue;
+
+      const containers: unknown[] = Array.isArray(props.ContainerDefinitions)
+        ? props.ContainerDefinitions
+        : [];
+
+      for (const container of containers) {
+        if (typeof container !== "object" || container === null) continue;
+        const c = container as Record<string, unknown>;
+
+        if (!isSolrImage(c.Image)) continue;
+
+        const envVars: unknown[] = Array.isArray(c.Environment) ? c.Environment : [];
+        const heapEntry = envVars.find(
+          (e): e is Record<string, unknown> =>
+            typeof e === "object" && e !== null && (e as Record<string, unknown>).Name === "SOLR_HEAP",
+        );
+
+        if (!heapEntry) continue; // WAW034 covers missing heap
+
+        const heapMb = parseHeapMb(String(heapEntry.Value ?? ""));
+        if (heapMb === null) continue;
+
+        if (heapMb > taskMemoryMb * 0.5) {
+          diagnostics.push({
+            checkId: "WAW033",
+            severity: "error",
+            message: `Solr container "${c.Name ?? "app"}" SOLR_HEAP (${heapMb}MB) exceeds 50% of task memory (${taskMemoryMb}MB) — risk of OOM kill; set SOLR_HEAP <= ${Math.floor(taskMemoryMb * 0.45)}m`,
+            entity: logicalId,
+            lexicon: "aws",
+          });
+        }
+      }
+    }
+  }
+
+  return diagnostics;
+}
+
+export const waw033: PostSynthCheck = {
+  id: "WAW033",
+  description: "Solr SOLR_HEAP exceeds 50% of Fargate task memory",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    return checkSolrHeapRatio(ctx);
+  },
+};

package/src/lint/post-synth/waw034.test.ts

@@ -0,0 +1,54 @@
+import { describe, test, expect } from "bun:test";
+import { createPostSynthContext } from "@intentius/chant-test-utils";
+import { waw034, checkSolrMemoryMinimum } from "./waw034";
+
+function makeTask(memory: string, image: string) {
+  return createPostSynthContext({
+    aws: {
+      Resources: {
+        SolrTask: {
+          Type: "AWS::ECS::TaskDefinition",
+          Properties: {
+            Memory: memory,
+            ContainerDefinitions: [{ Name: "app", Image: image }],
+          },
+        },
+      },
+    },
+  });
+}
+
+describe("WAW034: Solr Memory Minimum", () => {
+  test("check metadata", () => {
+    expect(waw034.id).toBe("WAW034");
+    expect(waw034.description).toContain("2048");
+  });
+
+  test("flags task with 512MB", () => {
+    const diags = checkSolrMemoryMinimum(makeTask("512", "solr:9"));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].checkId).toBe("WAW034");
+    expect(diags[0].severity).toBe("warning");
+    expect(diags[0].message).toContain("512MB");
+  });
+
+  test("flags task with 1024MB", () => {
+    const diags = checkSolrMemoryMinimum(makeTask("1024", "solr:9"));
+    expect(diags).toHaveLength(1);
+  });
+
+  test("no diagnostic at exactly 2048MB", () => {
+    const diags = checkSolrMemoryMinimum(makeTask("2048", "solr:9"));
+    expect(diags).toHaveLength(0);
+  });
+
+  test("no diagnostic at 4096MB", () => {
+    const diags = checkSolrMemoryMinimum(makeTask("4096", "solr:9"));
+    expect(diags).toHaveLength(0);
+  });
+
+  test("no diagnostic for non-solr image", () => {
+    const diags = checkSolrMemoryMinimum(makeTask("512", "postgres:16"));
+    expect(diags).toHaveLength(0);
+  });
+});

package/src/lint/post-synth/waw034.ts

@@ -0,0 +1,63 @@
+/**
+ * WAW034: Solr Container Undersized
+ *
+ * Fargate tasks running a Solr image with less than 2048MB of memory will
+ * fail under any real load — the JVM alone needs headroom for the heap plus
+ * OS file cache for Lucene MMap. 4096MB is the practical production minimum.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { parseCFTemplate } from "./cf-refs";
+
+function isSolrImage(image: unknown): boolean {
+  return typeof image === "string" && image.toLowerCase().includes("solr");
+}
+
+export function checkSolrMemoryMinimum(ctx: PostSynthContext): PostSynthDiagnostic[] {
+  const diagnostics: PostSynthDiagnostic[] = [];
+
+  for (const [_lexicon, output] of ctx.outputs) {
+    const template = parseCFTemplate(output);
+    if (!template?.Resources) continue;
+
+    for (const [logicalId, resource] of Object.entries(template.Resources)) {
+      if (resource.Type !== "AWS::ECS::TaskDefinition") continue;
+
+      const props = resource.Properties ?? {};
+      if (typeof props.Memory !== "string") continue;
+      const taskMemoryMb = parseInt(props.Memory);
+      if (!taskMemoryMb) continue;
+
+      const containers: unknown[] = Array.isArray(props.ContainerDefinitions)
+        ? props.ContainerDefinitions
+        : [];
+
+      const hasSolr = containers.some(
+        (c) => typeof c === "object" && c !== null && isSolrImage((c as Record<string, unknown>).Image),
+      );
+
+      if (!hasSolr) continue;
+
+      if (taskMemoryMb < 2048) {
+        diagnostics.push({
+          checkId: "WAW034",
+          severity: "warning",
+          message: `Solr task "${logicalId}" has only ${taskMemoryMb}MB memory — Solr requires at least 2048MB; 4096MB recommended for production`,
+          entity: logicalId,
+          lexicon: "aws",
+        });
+      }
+    }
+  }
+
+  return diagnostics;
+}
+
+export const waw034: PostSynthCheck = {
+  id: "WAW034",
+  description: "Fargate task running Solr has insufficient memory (< 2048MB)",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    return checkSolrMemoryMinimum(ctx);
+  },
+};

package/src/lint/post-synth/waw035.test.ts

@@ -0,0 +1,74 @@
+import { describe, test, expect } from "bun:test";
+import { createPostSynthContext } from "@intentius/chant-test-utils";
+import { waw035, checkSolrUlimits } from "./waw035";
+
+function makeTask(image: string, ulimits?: unknown[]) {
+  return createPostSynthContext({
+    aws: {
+      Resources: {
+        SolrTask: {
+          Type: "AWS::ECS::TaskDefinition",
+          Properties: {
+            Memory: "4096",
+            ContainerDefinitions: [
+              {
+                Name: "app",
+                Image: image,
+                ...(ulimits && { Ulimits: ulimits }),
+              },
+            ],
+          },
+        },
+      },
+    },
+  });
+}
+
+describe("WAW035: Solr nofile Ulimit", () => {
+  test("check metadata", () => {
+    expect(waw035.id).toBe("WAW035");
+    expect(waw035.description).toContain("nofile");
+  });
+
+  test("flags Solr container with no ulimits", () => {
+    const diags = checkSolrUlimits(makeTask("solr:9"));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].checkId).toBe("WAW035");
+    expect(diags[0].severity).toBe("warning");
+    expect(diags[0].message).toContain("not set");
+  });
+
+  test("flags Solr container with nofile below minimum", () => {
+    const diags = checkSolrUlimits(makeTask("solr:9", [
+      { Name: "nofile", SoftLimit: 1024, HardLimit: 1024 },
+    ]));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].message).toContain("1024");
+  });
+
+  test("no diagnostic when nofile >= 65535", () => {
+    const diags = checkSolrUlimits(makeTask("solr:9", [
+      { Name: "nofile", SoftLimit: 65535, HardLimit: 65535 },
+    ]));
+    expect(diags).toHaveLength(0);
+  });
+
+  test("no diagnostic when nofile HardLimit > 65535", () => {
+    const diags = checkSolrUlimits(makeTask("solr:9", [
+      { Name: "nofile", SoftLimit: 65535, HardLimit: 131072 },
+    ]));
+    expect(diags).toHaveLength(0);
+  });
+
+  test("no diagnostic for non-solr image", () => {
+    const diags = checkSolrUlimits(makeTask("nginx:latest"));
+    expect(diags).toHaveLength(0);
+  });
+
+  test("flags when only nproc ulimit set but nofile missing", () => {
+    const diags = checkSolrUlimits(makeTask("solr:9", [
+      { Name: "nproc", SoftLimit: 65535, HardLimit: 65535 },
+    ]));
+    expect(diags).toHaveLength(1);
+  });
+});

package/src/lint/post-synth/waw035.ts

@@ -0,0 +1,71 @@
+/**
+ * WAW035: Solr Container Missing nofile Ulimit
+ *
+ * Solr opens a file descriptor for every shard replica, index file, log, and
+ * connection. Without a raised nofile limit the process hits the default kernel
+ * limit (~1024) under moderate load, causing "Too many open files" errors that
+ * bring the node down. The production minimum is 65535.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { parseCFTemplate } from "./cf-refs";
+
+const NOFILE_MIN = 65535;
+
+function isSolrImage(image: unknown): boolean {
+  return typeof image === "string" && image.toLowerCase().includes("solr");
+}
+
+export function checkSolrUlimits(ctx: PostSynthContext): PostSynthDiagnostic[] {
+  const diagnostics: PostSynthDiagnostic[] = [];
+
+  for (const [_lexicon, output] of ctx.outputs) {
+    const template = parseCFTemplate(output);
+    if (!template?.Resources) continue;
+
+    for (const [logicalId, resource] of Object.entries(template.Resources)) {
+      if (resource.Type !== "AWS::ECS::TaskDefinition") continue;
+
+      const containers: unknown[] = Array.isArray(resource.Properties?.ContainerDefinitions)
+        ? resource.Properties.ContainerDefinitions
+        : [];
+
+      for (const container of containers) {
+        if (typeof container !== "object" || container === null) continue;
+        const c = container as Record<string, unknown>;
+
+        if (!isSolrImage(c.Image)) continue;
+
+        const ulimits: unknown[] = Array.isArray(c.Ulimits) ? c.Ulimits : [];
+        const nofile = ulimits.find(
+          (u): u is Record<string, unknown> =>
+            typeof u === "object" && u !== null && (u as Record<string, unknown>).Name === "nofile",
+        );
+
+        const hardLimit = nofile ? Number(nofile.HardLimit ?? 0) : 0;
+
+        if (!nofile || hardLimit < NOFILE_MIN) {
+          const current = nofile ? ` (current HardLimit: ${hardLimit})` : " (not set)";
+          diagnostics.push({
+            checkId: "WAW035",
+            severity: "warning",
+            message: `Solr container "${c.Name ?? "app"}" in task "${logicalId}" nofile ulimit${current} — set HardLimit >= ${NOFILE_MIN} to prevent "Too many open files" under load`,
+            entity: logicalId,
+            lexicon: "aws",
+          });
+        }
+      }
+    }
+  }
+
+  return diagnostics;
+}
+
+export const waw035: PostSynthCheck = {
+  id: "WAW035",
+  description: "Solr container missing nofile ulimit >= 65535",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    return checkSolrUlimits(ctx);
+  },
+};