@intentius/chant-lexicon-terraform 0.101.0 → 0.102.0

package/dist/rules/tf037.ts

@@ -0,0 +1,101 @@
+/**
+ * TF037: an ECR repository lets an image tag be repointed (chant #2288, epic
+ * #2284).
+ *
+ * The Terraform counterpart of the aws lexicon's WAW054, written natively.
+ *
+ * Absence is insecure for this resource, and the rule reports it.
+ * `aws_ecr_repository.image_tag_mutability` (provider
+ * `internal/service/ecr/repository.go`, v6.67.0) is optional with
+ * `Default: MUTABLE`, so a repository that does not set it lets anyone with
+ * push access move a tag (`prod`, `v1.4.2`) to different image content after
+ * it was deployed, scanned or signed.
+ *
+ * Provider v6 accepts four values (AWS added the two `_WITH_EXCLUSION` modes
+ * in 2025), and the rule reads them as follows:
+ *
+ * - `IMMUTABLE`: secure.
+ * - `IMMUTABLE_WITH_EXCLUSION`: secure. Tags matching an
+ *   `image_tag_mutability_exclusion_filter` stay mutable, a written-down
+ *   exception such as `latest`. A filter that is nothing but `*` excludes
+ *   every tag, so it is a finding; a filter from an expression is not
+ *   determined.
+ * - `MUTABLE`, absent, and `MUTABLE_WITH_EXCLUSION` (every tag mutable except
+ *   those the filters name): a finding.
+ * - an expression: not determined.
+ *
+ * Scope: root and child modules alike (#2112).
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import type { TerraformBlock } from "./blocks";
+import { finding, nestedBodies, notDetermined, readString, resourcesOfType } from "./flat-attributes";
+
+const ID = "TF037";
+
+const FIX =
+  'Set `image_tag_mutability = "IMMUTABLE"` and push a new tag for each build, or `"IMMUTABLE_WITH_EXCLUSION"` with ' +
+  "an `image_tag_mutability_exclusion_filter` for the few moving tags (`latest`) that must stay mutable.";
+
+const TAIL = "TF037 does not evaluate expressions, so it cannot tell whether this repository's tags are immutable.";
+
+/** A diagnostic for an `IMMUTABLE_WITH_EXCLUSION` repository, or nothing. */
+function checkExclusions(block: TerraformBlock): PostSynthDiagnostic | undefined {
+  for (const [i, f] of nestedBodies(block.body, "image_tag_mutability_exclusion_filter").entries()) {
+    const filter = readString(f, "filter");
+    if (filter.kind === "unknown") {
+      return notDetermined(ID, block, `exclusion filter ${i + 1}: ${filter.reason}`, TAIL);
+    }
+    if (filter.kind === "known" && /^\*+$/.test(filter.value)) {
+      return finding(
+        ID,
+        "error",
+        block,
+        `is \`IMMUTABLE_WITH_EXCLUSION\`, but exclusion filter ${i + 1} is "${filter.value}", which matches every tag, ` +
+          `so every tag stays mutable. ${FIX}`,
+      );
+    }
+  }
+  if (nestedBodies(block.body, "dynamic").some((d) => d.image_tag_mutability_exclusion_filter !== undefined)) {
+    return notDetermined(ID, block, 'has a `dynamic "image_tag_mutability_exclusion_filter"` block', TAIL);
+  }
+  return undefined;
+}
+
+export const tf037: PostSynthCheck = {
+  id: "TF037",
+  description: "ECR repository allows mutable image tags",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const out: PostSynthDiagnostic[] = [];
+    for (const block of resourcesOfType(ctx, "aws_ecr_repository")) {
+      const mode = readString(block.body, "image_tag_mutability");
+      if (mode.kind === "unknown") {
+        out.push(notDetermined(ID, block, mode.reason, TAIL));
+        continue;
+      }
+      if (mode.kind === "known" && mode.value === "IMMUTABLE") continue;
+      if (mode.kind === "known" && mode.value === "IMMUTABLE_WITH_EXCLUSION") {
+        const d = checkExclusions(block);
+        if (d) out.push(d);
+        continue;
+      }
+      const how =
+        mode.kind === "absent"
+          ? "does not set `image_tag_mutability`, and the provider default is `MUTABLE`"
+          : mode.value === "MUTABLE_WITH_EXCLUSION"
+            ? "is `MUTABLE_WITH_EXCLUSION`, so every tag the exclusion filters do not name stays mutable"
+            : `sets \`image_tag_mutability = "${mode.value}"\``;
+      out.push(
+        finding(
+          ID,
+          "error",
+          block,
+          `${how}: a pushed tag can later be repointed at different image content, so what was deployed, scanned or ` +
+            `signed under that tag is no longer what it names. ${FIX}`,
+        ),
+      );
+    }
+    return out;
+  },
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-terraform",
-  "version": "0.101.0",
+  "version": "0.102.0",
   "type": "module",
   "files": [
     "src/",
@@ -42,7 +42,7 @@
     "generate": "npx tsx src/codegen/generate-cli.ts",
     "validate": "npx tsx src/validate-cli.ts",
     "docs": "npx tsx src/codegen/docs-cli.ts",
-    "build": "tsc -p tsconfig.build.json && tsc-alias -p tsconfig.build.json && find dist -type f \\( -name \"*.js\" -o -name \"*.js.map\" \\) -delete",
+    "build": "../../scripts/tsc7.sh -p tsconfig.build.json && tsc-alias -p tsconfig.build.json && find dist -type f \\( -name \"*.js\" -o -name \"*.js.map\" \\) -delete",
     "prepack": "npm run generate && npm run bundle && npm run validate && npm run build",
     "bundle": "tsx src/package-cli.ts"
   },
@@ -57,7 +57,7 @@
     "access": "public"
   },
   "peerDependencies": {
-    "@intentius/chant": "^0.101.0",
+    "@intentius/chant": "^0.102.0",
     "typescript": "^5.9.3",
     "zod": "^4.3.6"
   },

package/src/hcl/jsonencode.test.ts

@@ -0,0 +1,226 @@
+import { describe, expect, test } from "vitest";
+import { hasUnknownKeys, isUnknown, readJsonencode, UNKNOWN, UNKNOWN_KEYS } from "./jsonencode";
+
+/** What hcl2json hands back for `attr = jsonencode(<arg>)`: the source text, wrapped as one interpolation. */
+const call = (arg: string): string => `\${jsonencode(${arg})}`;
+
+describe("readJsonencode: a literal jsonencode argument read as structure (chant #2286)", () => {
+  test("an IAM policy in HCL object syntax, as hcl2json renders it", () => {
+    const raw =
+      '${jsonencode({\n    Version = "2012-10-17"\n    Statement = [\n      {\n        Action   = ["s3:*", "ec2:Describe*"]\n' +
+      '        "Effect" : "Allow"\n        Resource = "*"\n      },\n    ]\n  })}';
+    expect(readJsonencode(raw)).toEqual({
+      kind: "literal",
+      value: {
+        Version: "2012-10-17",
+        Statement: [{ Action: ["s3:*", "ec2:Describe*"], Effect: "Allow", Resource: "*" }],
+      },
+    });
+  });
+
+  test("a container definitions tuple with commas, numbers, booleans and null", () => {
+    const raw = call('[{ name = "app", cpu = 256, essential = true, memory = null, portMappings = [{ containerPort = 80 }] }]');
+    expect(readJsonencode(raw)).toEqual({
+      kind: "literal",
+      value: [{ name: "app", cpu: 256, essential: true, memory: null, portMappings: [{ containerPort: 80 }] }],
+    });
+  });
+
+  test("scalars, negative and exponent numbers, and string escapes", () => {
+    expect(readJsonencode(call('"x"'))).toEqual({ kind: "literal", value: "x" });
+    expect(readJsonencode(call("-1.5e2"))).toEqual({ kind: "literal", value: -150 });
+    expect(readJsonencode(call('"a\\"b\\\\c\\n\\u00e9"'))).toEqual({ kind: "literal", value: 'a"b\\c\né' });
+    expect(readJsonencode(call('"$${literal} %%{also}"'))).toEqual({ kind: "literal", value: "${literal} %{also}" });
+  });
+
+  test("comments inside the argument are whitespace", () => {
+    const raw = call('{\n  # why\n  a = 1 // trailing\n  /* block */ b = "x"\n}');
+    expect(readJsonencode(raw)).toEqual({ kind: "literal", value: { a: 1, b: "x" } });
+  });
+
+  test("spacing around the call itself", () => {
+    expect(readJsonencode('${ jsonencode ( { a = 1 } ) }')).toEqual({ kind: "literal", value: { a: 1 } });
+  });
+
+  test.each([
+    ["a reference as a value", '{ Resource = var.arn }', /reference/],
+    ["a reference as the whole argument", "local.policy", /reference/],
+    ["a function call", '{ Resource = concat(["a"], var.b) }', /function call/],
+    ["a for-expression in a tuple", "[for a in var.actions : a]", /for-expression/],
+    ["a for-expression in an object", "{ for k, v in var.m : k => v }", /for-expression/],
+    ["a conditional", '{ Action = var.admin ? "*" : "s3:GetObject" }', /reference/],
+    ["a conditional on a literal", '{ Action = true ? "*" : "x" }', /conditional/],
+    ["an interpolated string", '{ Resource = "arn:aws:s3:::${var.bucket}/*" }', /interpolation/],
+    ["a template directive", '{ Resource = "%{ if true }x%{ endif }" }', /directive/],
+    ["an operator", "{ n = 1 + 2 }", /operator/],
+    ["a computed key", '{ (var.k) = "v" }', /computed object key/],
+    ["a heredoc", "<<EOT\n{}\nEOT\n", /heredoc/],
+    ["an index on a literal", '{ a = ["x"][0] }', /index/],
+  ])("not-determined: %s", (_name, arg, reason) => {
+    const read = readJsonencode(call(arg));
+    expect(read.kind).toBe("not-determined");
+    if (read.kind === "not-determined") expect(read.reason).toMatch(reason);
+  });
+
+  test("not-determined: two calls in one template, never literal", () => {
+    expect(readJsonencode('${jsonencode({a = 1})}-${jsonencode({b = 2})}').kind).toBe("not-determined");
+  });
+
+  test.each([
+    ["a plain string", '{"Statement":[]}'],
+    ["a reference", "${data.aws_iam_policy_document.x.json}"],
+    ["a file() call", '${file("policy.json")}'],
+    ["a templatefile() call", '${templatefile("p.tpl", { a = 1 })}'],
+    ["a template around a jsonencode call", 'x-${jsonencode({a = 1})}'],
+    ["a number", 3],
+    ["absent", undefined],
+    ["a structured value", { Statement: [] }],
+  ])("not-jsonencode: %s", (_name, raw) => {
+    expect(readJsonencode(raw)).toEqual({ kind: "not-jsonencode" });
+  });
+});
+
+describe("readJsonencode with unknownLeaves: expressions become opaque leaves", () => {
+  const leaves = (raw: string) => readJsonencode(raw, { unknownLeaves: true });
+
+  test("a literal Action survives beside a reference Resource", () => {
+    const read = leaves(call('{\n  Statement = [{\n    Action   = "*"\n    Resource = aws_s3_bucket.x.arn\n    Effect   = "Allow"\n  }]\n}'));
+    expect(read.kind).toBe("literal");
+    if (read.kind !== "literal") return;
+    const stmt = (read.value as { Statement: Record<string, unknown>[] }).Statement[0];
+    expect(stmt.Action).toBe("*");
+    expect(stmt.Effect).toBe("Allow");
+    expect(isUnknown(stmt.Resource)).toBe(true);
+    expect((stmt.Resource as { reason: string }).reason).toMatch(/reference/);
+    expect((stmt.Resource as Record<symbol, unknown>)[UNKNOWN]).toBe(true);
+    expect((stmt.Resource as { source: string }).source).toBe("aws_s3_bucket.x.arn");
+  });
+
+  test("container definitions keep their literal environment beside image = var.image", () => {
+    const read = leaves(
+      call('[{\n  name  = "app"\n  image = "${var.repo}:${var.tag}"\n  cpu   = var.cpu * 2\n  environment = [{ name = "DB_PASSWORD", value = "hunter2" }]\n}]'),
+    );
+    expect(read.kind).toBe("literal");
+    if (read.kind !== "literal") return;
+    const def = (read.value as Record<string, unknown>[])[0];
+    expect(def.name).toBe("app");
+    expect(isUnknown(def.image)).toBe(true);
+    expect((def.image as { source: string }).source).toBe('"${var.repo}:${var.tag}"');
+    expect(isUnknown(def.cpu)).toBe(true);
+    expect(def.environment).toEqual([{ name: "DB_PASSWORD", value: "hunter2" }]);
+  });
+
+  test.each([
+    ["a function call spanning lines", 'merge(\n  { a = "x" },\n  var.extra,\n)'],
+    ["a conditional with nested literals", 'var.admin ? { a = "*" } : {}'],
+    ["a heredoc", "<<EOT\n{\"a\": 1}\nEOT"],
+    ["an indexed tuple", '["x"][0]'],
+    ["a splat", "aws_s3_bucket.b[*].arn"],
+    ["a string with nested quotes in its interpolation", '"${lookup(var.m, "k", "}")}"'],
+  ])("skips %s and reads the next field", (_name, expr) => {
+    const read = leaves(call(`{\n  a = ${expr}\n  b = "after"\n}`));
+    expect(read.kind).toBe("literal");
+    if (read.kind !== "literal") return;
+    const v = read.value as Record<string, unknown>;
+    expect(isUnknown(v.a)).toBe(true);
+    expect(v.b).toBe("after");
+  });
+
+  test("tuple items are skipped one at a time", () => {
+    const read = leaves(call('["s3:GetObject", var.extra, "*"]'));
+    expect(read.kind).toBe("literal");
+    if (read.kind !== "literal") return;
+    const v = read.value as unknown[];
+    expect(v[0]).toBe("s3:GetObject");
+    expect(isUnknown(v[1])).toBe(true);
+    expect(v[2]).toBe("*");
+  });
+
+  test.each([
+    ["a tuple for-expression as the whole argument", "[for s in var.s : s]", /for-expression/],
+    ["an object for-expression as the whole argument", "{ for k, v in var.m : k => v }", /for-expression/],
+    ["an expression as the whole argument", "local.policy", /reference/],
+    ["a splat as the whole argument", "var.x[*]", /reference/],
+  ])("still not-determined: %s", (_name, arg, reason) => {
+    const read = leaves(call(arg));
+    expect(read.kind).toBe("not-determined");
+    if (read.kind === "not-determined") expect(read.reason).toMatch(reason);
+  });
+
+  test("the default mode is unchanged: one expression makes the whole read not-determined", () => {
+    expect(readJsonencode(call('{ Action = "*", Resource = var.arn }')).kind).toBe("not-determined");
+  });
+});
+
+describe("readJsonencode with unknownLeaves: members with an expression key", () => {
+  test("a traefik label keyed by an interpolation is dropped and recorded (govuk-forms/forms-admin shape)", () => {
+    const raw = call(
+      '[{\n  name = "forms-admin"\n  dockerLabels = {\n    "traefik.enable" : "true"\n' +
+        '    "traefik.http.routers.forms-admin-pr-${var.pull_request_number}.rule" : "Host(`pr-${var.pull_request_number}.example`)"\n' +
+        '    "traefik.port" : "3000"\n  }\n}]',
+    );
+    const read = readJsonencode(raw, { unknownLeaves: true });
+    expect(read.kind).toBe("literal");
+    if (read.kind !== "literal") return;
+    const labels = (read.value as Record<string, unknown>[])[0].dockerLabels as Record<string | symbol, unknown>;
+    expect(Object.keys(labels)).toEqual(["traefik.enable", "traefik.port"]);
+    expect(hasUnknownKeys(labels)).toBe(true);
+    expect(labels[UNKNOWN_KEYS]).toEqual([expect.stringMatching(/object key holding .*interpolation/)]);
+    expect(hasUnknownKeys((read.value as Record<string, unknown>[])[0])).toBe(false);
+  });
+
+  test("a parenthesised computed key is dropped with its multi-line value", () => {
+    const read = readJsonencode(call('{\n  (var.k) = {\n    x = 1\n  }\n  b = "after"\n}'), { unknownLeaves: true });
+    expect(read.kind).toBe("literal");
+    if (read.kind !== "literal") return;
+    expect(Object.keys(read.value as object)).toEqual(["b"]);
+    expect((read.value as Record<symbol, unknown>)[UNKNOWN_KEYS]).toEqual(["a computed object key"]);
+  });
+
+  test.each([
+    ["a computed key", '{ (var.k) = "v" }', /computed object key/],
+    ["an interpolated key", '{ "${var.k}" = "v" }', /object key/],
+  ])("default mode: %s makes the whole read not-determined", (_name, arg, reason) => {
+    const read = readJsonencode(call(arg));
+    expect(read.kind).toBe("not-determined");
+    if (read.kind === "not-determined") expect(read.reason).toMatch(reason);
+  });
+});
+
+describe("readJsonencode with unknownLeaves: a for-expression below the argument is a leaf", () => {
+  test("a tuple for-expression as a member value (sonodar/dify-aws-terraform shape)", () => {
+    const raw = call(
+      '[{\n  name = "api"\n  environment = [for name, value in {\n    MODE = "api"\n    LOG_LEVEL = "INFO"\n  } : { name = name, value = tostring(value) }]\n  essential = true\n}]',
+    );
+    const read = readJsonencode(raw, { unknownLeaves: true });
+    expect(read.kind).toBe("literal");
+    if (read.kind !== "literal") return;
+    const def = (read.value as Record<string, unknown>[])[0];
+    expect(def.name).toBe("api");
+    expect(isUnknown(def.environment)).toBe(true);
+    expect((def.environment as { reason: string }).reason).toMatch(/for-expression/);
+    expect(def.essential).toBe(true);
+  });
+
+  test("an object for-expression as a member value", () => {
+    const read = readJsonencode(call('{\n  labels = { for k, v in var.m : k => v }\n  b = 1\n}'), { unknownLeaves: true });
+    expect(read.kind).toBe("literal");
+    if (read.kind !== "literal") return;
+    const v = read.value as Record<string, unknown>;
+    expect(isUnknown(v.labels)).toBe(true);
+    expect(v.b).toBe(1);
+  });
+
+  test("a for-expression producing a policy's Statement list is one unknown leaf", () => {
+    const read = readJsonencode(call('{\n  Version = "2012-10-17"\n  Statement = [for s in var.statements : s]\n}'), { unknownLeaves: true });
+    expect(read.kind).toBe("literal");
+    if (read.kind !== "literal") return;
+    expect(isUnknown((read.value as Record<string, unknown>).Statement)).toBe(true);
+  });
+
+  test("a for-expression as a tuple item", () => {
+    const read = readJsonencode(call('["a", [for x in var.y : x]]'), { unknownLeaves: true });
+    expect(read.kind).toBe("literal");
+    if (read.kind === "literal") expect(isUnknown((read.value as unknown[])[1])).toBe(true);
+  });
+});