@intentius/chant-lexicon-terraform 0.101.0 → 0.104.0

package/src/lint/post-synth/fixtures/estate-2284/violating/main.tf

@@ -0,0 +1,112 @@
+# Epic #2284 acceptance estate, violating root. Written for chant, not
+# vendored: the fidelity probe's fixtures (docs/design/waw-hcl-fidelity-probe.md)
+# were never committed, so this root carries one violation per rule, TF030 to
+# TF037, each written the way a real estate writes it. `chant audit` over this
+# directory reports every one of them (src/lint/post-synth/estate-2284.test.ts).
+
+terraform {
+  required_version = ">= 1.5.0"
+
+  backend "s3" {
+    bucket = "acme-terraform-state"
+    key    = "payments/terraform.tfstate"
+    region = "eu-west-1"
+  }
+
+  required_providers {
+    aws = {
+      source  = "hashicorp/aws"
+      version = "~> 6.0"
+    }
+  }
+}
+
+provider "aws" {
+  region = "eu-west-1"
+}
+
+# TF030: SSH open to the world.
+resource "aws_security_group" "bastion" {
+  name   = "bastion"
+  vpc_id = "vpc-0a1b2c3d4e5f60718"
+
+  ingress {
+    from_port   = 22
+    to_port     = 22
+    protocol    = "tcp"
+    cidr_blocks = ["0.0.0.0/0"]
+  }
+}
+
+# TF031: an admin policy.
+resource "aws_iam_policy" "deployer" {
+  name = "deployer"
+  policy = jsonencode({
+    Version = "2012-10-17"
+    Statement = [
+      {
+        Effect   = "Allow"
+        Action   = "*"
+        Resource = "*"
+      },
+    ]
+  })
+}
+
+# TF032: a database password in a container's environment.
+resource "aws_ecs_task_definition" "api" {
+  family                   = "payments-api"
+  requires_compatibilities = ["FARGATE"]
+  network_mode             = "awsvpc"
+  cpu                      = "512"
+  memory                   = "1024"
+
+  container_definitions = jsonencode([{
+    name  = "api"
+    image = "public.ecr.aws/acme/payments-api:1.4.2"
+    environment = [
+      { name = "LOG_LEVEL", value = "info" },
+      { name = "DB_PASSWORD", value = "Pm-Pr0d-Db-2026!" }
+    ]
+  }])
+}
+
+# TF033: storage encryption written off.
+resource "aws_db_instance" "ledger" {
+  identifier          = "ledger"
+  engine              = "postgres"
+  instance_class      = "db.t4g.medium"
+  allocated_storage   = 50
+  username            = "ledger"
+  password            = var.db_password
+  storage_encrypted   = false
+  skip_final_snapshot = true
+}
+
+variable "db_password" {
+  type      = string
+  sensitive = true
+}
+
+# TF034: a topic that names no key.
+resource "aws_sns_topic" "alerts" {
+  name = "payments-alerts"
+}
+
+# TF035: SSE-SQS turned off.
+resource "aws_sqs_queue" "settlements" {
+  name                    = "settlements"
+  sqs_managed_sse_enabled = false
+}
+
+# TF036: a volume that asks not to be encrypted.
+resource "aws_ebs_volume" "scratch" {
+  availability_zone = "eu-west-1a"
+  size              = 100
+  encrypted         = false
+}
+
+# TF037: a repository left at the provider default, MUTABLE.
+resource "aws_ecr_repository" "api" {
+  name = "payments-api"
+}

package/src/lint/post-synth/flat-attributes.ts

@@ -0,0 +1,146 @@
+/**
+ * Shared reading helpers for TF033-TF037, the five flat encryption and
+ * immutability rules (chant #2288, epic #2284).
+ *
+ * Each of those rules reads one or two scalar attributes of one resource type
+ * and answers a three-valued question: the literal proves the resource
+ * secure, the literal proves it insecure, or the parse cannot tell. This
+ * module is the reading half; each rule file holds its own answer for
+ * absence, because that answer differs per resource (see each rule's doc
+ * comment and its section of `docs/pages/lint-rules.mdx`). It exports no
+ * `PostSynthCheck`, so the generated barrel skips it.
+ */
+
+import type { PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { RESOURCE_TYPE, type BlockBody } from "../../hcl/parse";
+import { attr } from "../../hcl/value";
+import { blocksOfType, nestedBodies, type TerraformBlock } from "./blocks";
+
+/** What one attribute read settles. `reason` says why a value could not be read. */
+export type Read<T> = { kind: "known"; value: T } | { kind: "absent" } | { kind: "unknown"; reason: string };
+
+/** Every `resource` block of one provider type (`aws_sqs_queue`), in entity order. */
+export function resourcesOfType(ctx: PostSynthContext, type: string): TerraformBlock[] {
+  return blocksOfType(ctx, RESOURCE_TYPE).filter((b) => b.address.startsWith(`${type}.`));
+}
+
+/** One expression, for a message: `var.encrypted`, or the template text. */
+function describe(name: string, raw: unknown, refs: string[] | undefined, kind: "reference" | "template"): string {
+  return kind === "reference"
+    ? `\`${name}\` is an expression (${refs?.[0] ?? String(raw)})`
+    : `\`${name}\` is a template string ("${String(raw)}")`;
+}
+
+/**
+ * A bool attribute. Terraform converts the strings `"true"` and `"false"` to
+ * bool, so those read as the bool they convert to. Any other literal (a
+ * number, a list) is a plan-time type error, not this rule's concern, and
+ * reads as unknown.
+ */
+export function readBool(body: BlockBody, name: string): Read<boolean> {
+  const a = attr(body, name);
+  if (a.kind === "absent") return { kind: "absent" };
+  if (a.kind === "reference" || a.kind === "template") {
+    return { kind: "unknown", reason: describe(name, a.raw, a.refs, a.kind) };
+  }
+  if (typeof a.value === "boolean") return { kind: "known", value: a.value };
+  if (a.value === "true" || a.value === "false") return { kind: "known", value: a.value === "true" };
+  return { kind: "unknown", reason: `\`${name}\` is not a bool (${JSON.stringify(a.value)})` };
+}
+
+/** A string attribute, literal or not. */
+export function readString(body: BlockBody, name: string): Read<string> {
+  const a = attr(body, name);
+  if (a.kind === "absent") return { kind: "absent" };
+  if (a.kind === "reference" || a.kind === "template") {
+    return { kind: "unknown", reason: describe(name, a.raw, a.refs, a.kind) };
+  }
+  if (typeof a.value === "string") return { kind: "known", value: a.value };
+  return { kind: "unknown", reason: `\`${name}\` is not a string (${JSON.stringify(a.value)})` };
+}
+
+/** Expression roots that name an input or a computed value, not a managed object. */
+const VALUE_ROOTS = new Set(["var", "local", "module", "each", "count", "path", "terraform", "self"]);
+
+/** `aws_kms_key.sns.arn`, `data.aws_kms_alias.sqs.target_key_arn`, with an optional index or splat. */
+const OBJECT_ATTRIBUTE = /^(?:data\.)?([a-z][a-z0-9_]*)\.[A-Za-z_][\w-]*(?:\[[^\]]*\])?(?:\.[A-Za-z_][\w-]*|\[[^\]]*\])+$/;
+
+/** Every `${...}` span in a template, as `attr()` finds them. */
+const SPANS = /\$\{(?:[^{}]|\{[^{}]*\})*\}/g;
+
+/**
+ * Whether a key-like argument (`kms_master_key_id`) is set to something.
+ *
+ * - absent, or `null`: `absent`.
+ * - a literal: `known`, with the string (`""` is a value, and a rule decides
+ *   what an empty key means).
+ * - an attribute of a managed resource or data source (`aws_kms_key.x.arn`):
+ *   `known` and non-empty. The provider computes a key's id or ARN; it is
+ *   never the empty string, so the key is set whatever its value turns out to
+ *   be.
+ * - a template with literal text (`"alias/${var.env}-sns"`): `known` and
+ *   non-empty, for the same reason.
+ * - anything else (`var.kms_key`, `local.key`, a conditional, a function
+ *   call): `unknown`. A variable can be `null` or `""`.
+ */
+export function readKeySet(body: BlockBody, name: string): Read<string> {
+  const a = attr(body, name);
+  if (a.kind === "absent") return { kind: "absent" };
+  if (a.kind === "literal") {
+    return typeof a.value === "string"
+      ? { kind: "known", value: a.value }
+      : { kind: "unknown", reason: `\`${name}\` is not a string (${JSON.stringify(a.value)})` };
+  }
+  const raw = String(a.raw);
+  if (a.kind === "template") {
+    if (raw.replace(SPANS, "").length > 0) return { kind: "known", value: raw };
+    return { kind: "unknown", reason: describe(name, a.raw, a.refs, "template") };
+  }
+  const expr = (a.refs?.[0] ?? "").trim();
+  const m = OBJECT_ATTRIBUTE.exec(expr);
+  if (m && !VALUE_ROOTS.has(m[1])) return { kind: "known", value: raw };
+  return { kind: "unknown", reason: describe(name, a.raw, a.refs, "reference") };
+}
+
+/**
+ * Whether an argument that names a source (`snapshot_identifier`,
+ * `replicate_source_db`) or a nested block (`restore_to_point_in_time`) is
+ * given. The provider reads these with `GetOk`, so a literal `""` is the same
+ * as leaving the argument out; anything else, a reference included, is given.
+ */
+export function isGiven(body: BlockBody, name: string): boolean {
+  const a = attr(body, name);
+  if (a.kind === "absent") return false;
+  if (a.kind === "literal") {
+    if (a.value === "" || a.value === false) return false;
+    if (Array.isArray(a.value)) return a.value.length > 0;
+  }
+  return true;
+}
+
+/** The bodies of a nested block, re-exported for the rule files. */
+export { nestedBodies };
+
+/** A finding the literal proves. */
+export function finding(
+  checkId: string,
+  severity: "error" | "warning",
+  block: TerraformBlock,
+  message: string,
+): PostSynthDiagnostic {
+  return { checkId, severity, message: `"${block.address}" ${message}`, entity: block.key, lexicon: "terraform" };
+}
+
+/**
+ * The one `info` diagnostic a rule emits when it cannot read the value it
+ * needs. The message starts `Not determined:`, as #2284 fixed for TF030-TF037.
+ */
+export function notDetermined(checkId: string, block: TerraformBlock, reason: string, tail: string): PostSynthDiagnostic {
+  return {
+    checkId,
+    severity: "info",
+    message: `Not determined: "${block.address}" ${reason}. ${tail}`,
+    entity: block.key,
+    lexicon: "terraform",
+  };
+}

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

@@ -28,6 +28,22 @@ import { tf026 } from "./tf026";
 import { tf027 } from "./tf027";
 import { tf028 } from "./tf028";
 import { tf029 } from "./tf029";
+import { tf030 } from "./tf030";
+import { tf031 } from "./tf031";
+import { tf032 } from "./tf032";
+import { tf033 } from "./tf033";
+import { tf034 } from "./tf034";
+import { tf035 } from "./tf035";
+import { tf036 } from "./tf036";
+import { tf037 } from "./tf037";
+import { tf038 } from "./tf038";
+import { tf039 } from "./tf039";
+import { tf040 } from "./tf040";
+import { tf041 } from "./tf041";
+import { tf042 } from "./tf042";
+import { tf043 } from "./tf043";
+import { tf044 } from "./tf044";
+import { tf045 } from "./tf045";
 
 export const postSynthChecks: PostSynthCheck[] = [
   tf001,
@@ -58,4 +74,20 @@ export const postSynthChecks: PostSynthCheck[] = [
   tf027,
   tf028,
   tf029,
+  tf030,
+  tf031,
+  tf032,
+  tf033,
+  tf034,
+  tf035,
+  tf036,
+  tf037,
+  tf038,
+  tf039,
+  tf040,
+  tf041,
+  tf042,
+  tf043,
+  tf044,
+  tf045,
 ];

package/src/lint/post-synth/module-source.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, test } from "vitest";
-import { classifyModuleSource, isDefaultBranch, isPinnedRef } from "./module-source";
+import { classifyModuleSource, isDefaultBranch, isExactVersionConstraint, isMutableOciTag, isPinnedRef } from "./module-source";
 
 describe("classifyModuleSource", () => {
   test("local paths", () => {
@@ -73,3 +73,44 @@ describe("isDefaultBranch", () => {
     expect(isDefaultBranch("some-feature")).toBe(false);
   });
 });
+
+describe("classifyModuleSource: oci sources (#3190)", () => {
+  const cases: Array<[string, string, string | undefined, string | undefined]> = [
+    ["tag query", "oci://example.com/org/mod?tag=v1.4.0", "v1.4.0", undefined],
+    ["digest query", "oci://example.com/org/mod?digest=sha256:abc123", undefined, "sha256:abc123"],
+    ["tag suffix", "oci://example.com/org/mod:1.4.0", "1.4.0", undefined],
+    ["digest suffix", "oci://example.com/org/mod@sha256:abc123", undefined, "sha256:abc123"],
+    ["tag and digest suffix", "oci://example.com/org/mod:1.4.0@sha256:abc123", "1.4.0", "sha256:abc123"],
+    ["tag and digest query", "oci://example.com/org/mod?tag=1.4.0&digest=sha256:abc123", "1.4.0", "sha256:abc123"],
+    ["neither", "oci://example.com/org/mod", undefined, undefined],
+    ["host with a port, no tag", "oci://registry.example.com:5000/org/mod", undefined, undefined],
+    ["host with a port and a tag", "oci://registry.example.com:5000/org/mod:2.0.1", "2.0.1", undefined],
+    ["host with a port and a digest", "oci://registry.example.com:5000/org/mod@sha256:def", undefined, "sha256:def"],
+    ["subdirectory before the query", "oci://example.com/org/mod//modules/vpc?tag=v1.0.0", "v1.0.0", undefined],
+    ["subdirectory, no pin", "oci://example.com/org/mod//modules/vpc", undefined, undefined],
+  ];
+
+  test.each(cases)("%s", (_name, source, tag, digest) => {
+    const c = classifyModuleSource(source);
+    expect(c.kind).toBe("oci");
+    expect(c.tag).toBe(tag);
+    expect(c.digest).toBe(digest);
+  });
+});
+
+describe("isMutableOciTag", () => {
+  test("names that move are mutable, versions are not", () => {
+    expect(isMutableOciTag("latest")).toBe(true);
+    expect(isMutableOciTag("LATEST")).toBe(true);
+    expect(isMutableOciTag("main")).toBe(true);
+    expect(isMutableOciTag("1.4.0")).toBe(false);
+    expect(isMutableOciTag("v1.4.0")).toBe(false);
+  });
+});
+
+describe("isExactVersionConstraint", () => {
+  test.each([["1.4.0", true], ["= 1.4.0", true], ["=1.4.0", true], ["1.4.0-rc1", true], ["~> 1.4", false], [">= 1.4", false], [">= 1.0, < 2.0", false], ["!= 1.4.0", false], ["< 2", false]])(
+    "%s",
+    (v, exact) => expect(isExactVersionConstraint(v as string)).toBe(exact),
+  );
+});

package/src/lint/post-synth/module-source.ts

@@ -18,14 +18,27 @@
  * recognize, scp-style `git@host:path` addresses, and any source ending in
  * `.git`. `local` is `./` or `../` (checkov's `UNKNOWN` case for module
  * pinning: a local path cannot be pinned to anything and is never flagged).
+ * `oci` is an OpenTofu `oci://host/repo` source (#3190). OpenTofu selects a
+ * version with `?tag=` or `?digest=` (https://opentofu.org/docs/language/modules/sources/),
+ * and a source naming neither resolves the `latest` tag. The container-image
+ * shapes `repo:tag` and `repo@sha256:...` are read too, so a source written
+ * the way `docker pull` spells it is not misread as unpinned. A `:` inside the
+ * host (a registry port) is never a tag: only a colon in the last path
+ * segment is. The tag and digest rules were checked against the docs page
+ * above; the suffix forms are not documented there and are not verified
+ * against OpenTofu's parser.
  */
 
-export type ModuleSourceKind = "local" | "registry" | "git" | "other";
+export type ModuleSourceKind = "local" | "registry" | "git" | "oci" | "other";
 
 export interface ModuleSourceClassification {
   kind: ModuleSourceKind;
   /** The `?ref=`/`&ref=` value (falling back to `rev`), when `kind` is `"git"`. */
   ref?: string;
+  /** The tag an `oci://` source names, from `?tag=` or a `:tag` suffix on the repository. */
+  tag?: string;
+  /** The digest an `oci://` source names, from `?digest=` or an `@sha256:...` suffix. */
+  digest?: string;
 }
 
 const REGISTRY_NAME = /^[0-9A-Za-z](?:[0-9A-Za-z_-]{0,62}[0-9A-Za-z])?$/;
@@ -77,6 +90,25 @@ function isGitShaped(rest: string): boolean {
   return false;
 }
 
+function classifyOci(base: string, query: string): ModuleSourceClassification {
+  const params = parseQuery(query);
+  let path = stripSubdir(base).replace(/^oci:\/\//i, "");
+  let tag = params.get("tag") || undefined;
+  let digest = params.get("digest") || undefined;
+
+  const at = path.indexOf("@");
+  if (at !== -1) {
+    digest = digest ?? (path.slice(at + 1) || undefined);
+    path = path.slice(0, at);
+  }
+  const lastSlash = path.lastIndexOf("/");
+  const colon = path.indexOf(":", lastSlash + 1); // a port sits before the first slash
+  if (colon !== -1) {
+    tag = tag ?? (path.slice(colon + 1) || undefined);
+  }
+  return { kind: "oci", ...(tag !== undefined ? { tag } : {}), ...(digest !== undefined ? { digest } : {}) };
+}
+
 export function classifyModuleSource(source: string): ModuleSourceClassification {
   const trimmed = source.trim();
   if (trimmed.startsWith("./") || trimmed.startsWith("../") || trimmed.startsWith(".\\") || trimmed.startsWith("..\\")) {
@@ -87,6 +119,8 @@ export function classifyModuleSource(source: string): ModuleSourceClassification
   const base = queryIdx === -1 ? trimmed : trimmed.slice(0, queryIdx);
   const query = queryIdx === -1 ? "" : trimmed.slice(queryIdx + 1);
 
+  if (/^oci:\/\//i.test(base)) return classifyOci(base, query);
+
   const forced = /^(git|hg)::/i.exec(base);
   const rest = forced ? base.slice(forced[0].length) : base;
 
@@ -119,3 +153,24 @@ export function isPinnedRef(ref: string): boolean {
 export function isDefaultBranch(ref: string): boolean {
   return DEFAULT_BRANCHES.has(ref);
 }
+
+const MUTABLE_TAGS = new Set(["latest", "main", "master", "develop", "dev", "stable", "edge", "nightly"]);
+
+/**
+ * Is `tag` a name that conventionally moves (`latest`, a branch-like name)
+ * rather than an exact version. Used by TF038. A tag is a mutable pointer in
+ * most registries whatever it looks like, so the rule is a warning and this
+ * only decides what reads as obviously floating.
+ */
+export function isMutableOciTag(tag: string): boolean {
+  return MUTABLE_TAGS.has(tag.toLowerCase());
+}
+
+/**
+ * Is a registry `version` constraint an exact version (`1.4.0`, `= 1.4.0`,
+ * `=1.4.0`) rather than a range (`~> 1.4`, `>= 1.4`, `>= 1.0, < 2.0`). Used
+ * by TF039. A bare version is an exact constraint in Terraform.
+ */
+export function isExactVersionConstraint(version: string): boolean {
+  return /^(?:=\s*)?v?\d+(?:\.\d+){0,2}(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/.test(version.trim()) && !version.includes(",");
+}

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

@@ -0,0 +1,76 @@
+/**
+ * Shared reading for the Terragrunt rules TF041 to TF045 (#3417).
+ *
+ * These rules look at `terragrunt.hcl` and `root.hcl`, which the parse reads
+ * into their own entity types (`TERRAGRUNT_*_TYPE` in `../../hcl/parse.ts`)
+ * and never into the module types the other TF rules check. Like the module
+ * source rules, they read the literal values hcl2json hands back: an
+ * attribute built from a function or a `local.` reference arrives as a
+ * `"${...}"` string and is treated as not determined, never as a finding.
+ */
+
+import { isResourceDeclarable, type Declarable } from "@intentius/chant/declarable";
+import type { BlockBody } from "../../hcl/parse";
+import { classifyModuleSource } from "./module-source";
+
+/** Entities of one Terragrunt type, with their keys, in map order. */
+export function terragruntEntities(
+  entities: ReadonlyMap<string, Declarable>,
+  entityType: string,
+): Array<{ key: string; address: string; file: string; body: BlockBody }> {
+  const out: Array<{ key: string; address: string; file: string; body: BlockBody }> = [];
+  for (const [key, entity] of entities) {
+    if (entity.entityType !== entityType || !isResourceDeclarable(entity)) continue;
+    const props = entity.props as { address?: unknown; file?: unknown; body?: unknown };
+    out.push({
+      key,
+      address: typeof props.address === "string" ? props.address : key,
+      file: typeof props.file === "string" ? props.file : "terragrunt.hcl",
+      body: (typeof props.body === "object" && props.body !== null ? props.body : {}) as BlockBody,
+    });
+  }
+  return out;
+}
+
+/** An HCL expression hcl2json left as `"${...}"`: its value is not known without evaluating it. */
+export function isExpression(value: unknown): boolean {
+  return typeof value === "string" && value.includes("${");
+}
+
+export type TerragruntSourceKind = "local" | "git" | "tfr" | "oci" | "other";
+
+export interface TerragruntSourceClassification {
+  kind: TerragruntSourceKind;
+  /** Whether the source names a version: `?ref=` for git, `?version=` for `tfr://`, a tag or digest for `oci://`. Undefined for `local` and `other`. */
+  pinned?: boolean;
+}
+
+/**
+ * Classify a unit's `terraform.source`. Git and `oci://` sources go through
+ * {@link classifyModuleSource}, the reader TF005 and TF038 use. `tfr://` is
+ * Terragrunt's own scheme for registry modules and takes its version from the
+ * `?version=` query argument. A source that holds an interpolation, or that
+ * names an absolute path or an archive URL, is `other` or `local` and is
+ * never reported.
+ */
+export function classifyTerragruntSource(source: string): TerragruntSourceClassification {
+  const trimmed = source.trim();
+  if (trimmed.includes("${")) return { kind: "other" };
+  if (/^tfr:\/\//i.test(trimmed)) {
+    const query = trimmed.includes("?") ? trimmed.slice(trimmed.indexOf("?") + 1) : "";
+    const version = new URLSearchParams(query).get("version");
+    return { kind: "tfr", pinned: version !== null && version.trim() !== "" };
+  }
+  if (trimmed.startsWith("/")) return { kind: "local" };
+  const classified = classifyModuleSource(trimmed);
+  switch (classified.kind) {
+    case "local":
+      return { kind: "local" };
+    case "git":
+      return { kind: "git", pinned: classified.ref !== undefined };
+    case "oci":
+      return { kind: "oci", pinned: classified.tag !== undefined || classified.digest !== undefined };
+    default:
+      return { kind: "other" };
+  }
+}

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

@@ -51,7 +51,7 @@ function providerNameFromType(type: string): string {
 }
 
 /** One implied provider name to the entity key that first implied it in file order. */
-function impliedProviders(entities: PostSynthContext["entities"], root: string): Map<string, string> {
+export function impliedProviders(entities: PostSynthContext["entities"], root: string): Map<string, string> {
   const implied = new Map<string, string>();
   const fromProviderBlock = new Set<string>();