@intentius/chant-lexicon-terraform 0.57.0 → 0.58.0

package/dist/rules/tf008.ts

@@ -0,0 +1,75 @@
+/**
+ * TF008: a `provider` block configures a credential inline.
+ *
+ * The most corroborated rule in #2107's survey: checkov (`CKV_AWS_41` and its
+ * `credentials.py` siblings), KICS, Snyk and semgrep all ship a version of it,
+ * and it is the only Terraform-language-shaped check any of Snyk or semgrep
+ * ships at all. Every one of them is written per provider. This one is written
+ * against attribute NAMES, so it covers the providers those tools cover and
+ * the several hundred they do not.
+ *
+ * A credential in a provider block is used by every resource that provider
+ * manages, so it is the highest-value one in the root, and it is read from the
+ * repository by everyone who can clone it. Providers all accept the same
+ * credential through the environment or a shared config file instead.
+ *
+ * Scope: root and child modules alike (#2112). The condition is a property
+ * of the block itself, so a descended module's block is read exactly as a
+ * root's is.
+ */
+
+import type {
+  PostSynthCheck,
+  PostSynthContext,
+  PostSynthDiagnostic,
+} from "@intentius/chant/lint/post-synth";
+import { PROVIDER_TYPE } from "../../hcl/parse";
+import { isLiteralString, isPlaceholderValue, isSecretName } from "../secret-shape";
+import { blockName, blocksOfType, walkAttributes } from "./blocks";
+
+/**
+ * Credential attributes the name heuristic in `../secret-shape.ts` does not
+ * cover on its own. `client_secret` and the `*_key`/`*_token` names it does
+ * cover are not repeated here.
+ */
+const PROVIDER_CREDENTIAL_ATTRS = new Set(["credentials", "client_certificate", "client_key", "shared_credentials_file"]);
+
+/**
+ * A path, not a credential: `credentials = "keys/service-account.json"` and
+ * `shared_credentials_file = "~/.aws/credentials"` name where the secret lives,
+ * which is what the fix looks like.
+ */
+const FILE_PATH_RE = /^[~./]?[\w./\\-]*\.(json|pem|key|p12|pfx|crt|cer|ini|conf|credentials)$/i;
+
+export const tf008: PostSynthCheck = {
+  id: "TF008",
+  description: "Provider block configures a hardcoded credential",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const block of blocksOfType(ctx, PROVIDER_TYPE)) {
+      for (const attr of walkAttributes(block.body)) {
+        if (!PROVIDER_CREDENTIAL_ATTRS.has(attr.name) && !isSecretName(attr.name)) continue;
+        if (!isLiteralString(attr.value)) continue;
+        const value = attr.value.trim();
+        if (value === "" || isPlaceholderValue(value) || FILE_PATH_RE.test(value)) continue;
+
+        diagnostics.push({
+          checkId: "TF008",
+          severity: "error",
+          message:
+            `Provider "${blockName(block.address)}" sets \`${attr.path}\` to a literal value ` +
+            `(${value.length} characters, redacted here). A credential in a provider block is ` +
+            "committed to the repository and used by every resource the provider manages. Remove it " +
+            "and let the provider read the credential from the environment, a shared config file, or " +
+            "a sensitive variable.",
+          entity: `${block.key}.${attr.path}`,
+          lexicon: "terraform",
+        });
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/dist/rules/tf009.ts

@@ -0,0 +1,59 @@
+/**
+ * TF009: a credential-named variable is not marked `sensitive`.
+ *
+ * No tool in #2107's survey checks this. The authority is HashiCorp's own style
+ * guide, whose variables section says plainly: "For sensitive variables, such
+ * as passwords and private keys, set the sensitive parameter to true."
+ *
+ * Without the flag the value is echoed in `terraform plan` and
+ * `terraform apply` output, which means it lands in CI logs, in the pull
+ * request comment a plan bot posts, and in every terminal scrollback. The flag
+ * does not keep the value out of state (nothing does), which is why the
+ * remediation says both things.
+ *
+ * Only the name is read. A variable with no default and no value in the
+ * repository is still flagged, because the finding is about where the value
+ * goes at run time, not about what is committed. That is TF007's question.
+ *
+ * Scope: root and child modules alike (#2112). The condition is a property
+ * of the block itself, so a descended module's block is read exactly as a
+ * root's is.
+ */
+
+import type {
+  PostSynthCheck,
+  PostSynthContext,
+  PostSynthDiagnostic,
+} from "@intentius/chant/lint/post-synth";
+import { VARIABLE_TYPE } from "../../hcl/parse";
+import { isSecretName } from "../secret-shape";
+import { blockName, blocksOfType } from "./blocks";
+
+export const tf009: PostSynthCheck = {
+  id: "TF009",
+  description: "Credential-named variable is not marked sensitive",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const block of blocksOfType(ctx, VARIABLE_TYPE)) {
+      const name = blockName(block.address);
+      if (!isSecretName(name)) continue;
+      if (block.body.sensitive === true) continue;
+
+      diagnostics.push({
+        checkId: "TF009",
+        severity: "error",
+        message:
+          `Variable "${name}" is named like a credential but is not marked \`sensitive = true\`, so ` +
+          "Terraform prints its value in plan and apply output, and from there into CI logs and plan " +
+          "comments. Add `sensitive = true`, and remember the value is still stored in plaintext in " +
+          "state either way.",
+        entity: block.key,
+        lexicon: "terraform",
+      });
+    }
+
+    return diagnostics;
+  },
+};

package/dist/rules/tf010.ts

@@ -0,0 +1,51 @@
+/**
+ * TF010: a `variable` declares no `type`.
+ *
+ * Without a type constraint Terraform accepts whatever it is given and infers
+ * the type from the value, so a variable meant to be a list arrives as a
+ * string from a `TF_VAR_` environment variable, or a number arrives as `"3"`
+ * from a tfvars file, and the failure surfaces deep inside a resource
+ * argument rather than at the module boundary where it was introduced.
+ *
+ * A blank `type` counts as absent, matching KICS, which fails a `type` that
+ * trims to empty.
+ *
+ * Scope: root and child modules alike (#2112). The condition is a property
+ * of the block itself, so a descended module's block is read exactly as a
+ * root's is.
+ */
+
+import type {
+  PostSynthCheck,
+  PostSynthContext,
+  PostSynthDiagnostic,
+} from "@intentius/chant/lint/post-synth";
+import { VARIABLE_TYPE } from "../../hcl/parse";
+import { blockName, blocksOfType, isBlank } from "./blocks";
+
+export const tf010: PostSynthCheck = {
+  id: "TF010",
+  description: "Variable declares no type constraint",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const block of blocksOfType(ctx, VARIABLE_TYPE)) {
+      if (!isBlank(block.body.type)) continue;
+
+      diagnostics.push({
+        checkId: "TF010",
+        severity: "info",
+        message:
+          `Variable "${blockName(block.address)}" declares no \`type\`, so Terraform accepts any ` +
+          "value and infers the type from whatever it is given. Add a type constraint " +
+          "(`string`, `number`, `bool`, `list(string)`, an `object({...})`) so a wrong value is " +
+          "rejected at the module boundary.",
+        entity: block.key,
+        lexicon: "terraform",
+      });
+    }
+
+    return diagnostics;
+  },
+};

package/dist/rules/tf011.ts

@@ -0,0 +1,49 @@
+/**
+ * TF011: a `variable` declares no `description`.
+ *
+ * A module's variables are its API. The description is what `terraform-docs`
+ * renders into the README, what the HCP Terraform and Terraform Cloud variable
+ * UI shows next to the input box, and what a caller reads before deciding what
+ * to pass. Without it the only documentation is the variable's name.
+ *
+ * Report-only: this is documentation hygiene, filed the way KICS files it (as
+ * INFO) and the way tflint files it (in the `all` preset, not `recommended`).
+ *
+ * Scope: root and child modules alike (#2112). The condition is a property
+ * of the block itself, so a descended module's block is read exactly as a
+ * root's is.
+ */
+
+import type {
+  PostSynthCheck,
+  PostSynthContext,
+  PostSynthDiagnostic,
+} from "@intentius/chant/lint/post-synth";
+import { VARIABLE_TYPE } from "../../hcl/parse";
+import { blockName, blocksOfType, isBlank } from "./blocks";
+
+export const tf011: PostSynthCheck = {
+  id: "TF011",
+  description: "Variable declares no description",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const block of blocksOfType(ctx, VARIABLE_TYPE)) {
+      if (!isBlank(block.body.description)) continue;
+
+      diagnostics.push({
+        checkId: "TF011",
+        severity: "info",
+        message:
+          `Variable "${blockName(block.address)}" declares no \`description\`, so the module's ` +
+          "generated documentation and the variable prompt have nothing to show but the name. Add a " +
+          "description saying what the value is for and what a valid one looks like.",
+        entity: block.key,
+        lexicon: "terraform",
+      });
+    }
+
+    return diagnostics;
+  },
+};

package/dist/rules/tf012.ts

@@ -0,0 +1,47 @@
+/**
+ * TF012: an `output` declares no `description`.
+ *
+ * The other half of a module's API. An output is what a caller wires into the
+ * next module, and the description is the only place to say what the value
+ * actually is (an id or an ARN, a full URL or a bare hostname) and whether it
+ * is stable enough to depend on.
+ *
+ * Report-only, for the same reason TF011 is.
+ *
+ * Scope: root and child modules alike (#2112). The condition is a property
+ * of the block itself, so a descended module's block is read exactly as a
+ * root's is.
+ */
+
+import type {
+  PostSynthCheck,
+  PostSynthContext,
+  PostSynthDiagnostic,
+} from "@intentius/chant/lint/post-synth";
+import { OUTPUT_TYPE } from "../../hcl/parse";
+import { blockName, blocksOfType, isBlank } from "./blocks";
+
+export const tf012: PostSynthCheck = {
+  id: "TF012",
+  description: "Output declares no description",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const block of blocksOfType(ctx, OUTPUT_TYPE)) {
+      if (!isBlank(block.body.description)) continue;
+
+      diagnostics.push({
+        checkId: "TF012",
+        severity: "info",
+        message:
+          `Output "${blockName(block.address)}" declares no \`description\`. Outputs are a module's ` +
+          "public interface, so say what the value is and what a caller can rely on it for.",
+        entity: block.key,
+        lexicon: "terraform",
+      });
+    }
+
+    return diagnostics;
+  },
+};

package/dist/rules/tf013.ts

@@ -0,0 +1,63 @@
+/**
+ * TF013: `lifecycle { ignore_changes = all }`.
+ *
+ * `all` tells Terraform to ignore drift on every attribute of the resource
+ * after it is created. Nothing about that resource is ever reconciled again:
+ * a manual console edit, a deleted security-group rule, a downgraded instance
+ * class, all of it plans clean forever. It is also silent, because a plan that
+ * finds nothing looks exactly like a plan that was told to look at nothing.
+ *
+ * That is the observe half of chant's lifecycle switched off, so this is
+ * merge-worthy rather than hygiene. A list of specific attributes is fine and
+ * is not reported: ignoring `tags` an external tool writes is a real need, and
+ * naming them is what makes the intent auditable.
+ *
+ * Scope: root and child modules alike (#2112). The condition is a property
+ * of the block itself, so a descended module's block is read exactly as a
+ * root's is.
+ */
+
+import type {
+  PostSynthCheck,
+  PostSynthContext,
+  PostSynthDiagnostic,
+} from "@intentius/chant/lint/post-synth";
+import { DATA_TYPE, RESOURCE_TYPE } from "../../hcl/parse";
+import { blocksOfTypes, nestedBodies } from "./blocks";
+
+/**
+ * `ignore_changes = all` parses to the string `"${all}"`: hcl2json renders the
+ * bare keyword as an expression template. A list of attributes parses to an
+ * array, so an array is only a match if `all` is the whole of it.
+ */
+function ignoresEverything(value: unknown): boolean {
+  if (value === "${all}") return true;
+  return Array.isArray(value) && value.length === 1 && value[0] === "${all}";
+}
+
+export const tf013: PostSynthCheck = {
+  id: "TF013",
+  description: "lifecycle ignore_changes is set to all",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const block of blocksOfTypes(ctx, [RESOURCE_TYPE, DATA_TYPE])) {
+      for (const lifecycle of nestedBodies(block.body, "lifecycle")) {
+        if (!ignoresEverything(lifecycle.ignore_changes)) continue;
+        diagnostics.push({
+          checkId: "TF013",
+          severity: "warning",
+          message:
+            `"${block.address}" sets \`ignore_changes = all\`, so Terraform stops reconciling every ` +
+            "attribute of the resource after it is created. Drift becomes invisible: a manual change " +
+            "in the console plans clean forever. List the specific attributes to ignore instead.",
+          entity: block.key,
+          lexicon: "terraform",
+        });
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/dist/rules/tf014.ts

@@ -0,0 +1,72 @@
+/**
+ * TF014: a `provider` block inside a child module that configures anything.
+ *
+ * Scope: child modules only. A `provider` block in the ROOT module is where
+ * providers are supposed to be configured, and TF008 is what checks its
+ * contents.
+ *
+ * A child module that configures its own provider takes the decision away
+ * from its caller: the caller can no longer point the module at a different
+ * region, account or endpoint, and two calls of the module in one root cannot
+ * differ. Worse, Terraform cannot remove a module whose provider is declared
+ * inside it, because destroying the resources needs a provider configuration
+ * that the removal itself deletes. That is the "Provider configuration not
+ * present" failure that leaves a root unable to plan.
+ *
+ * The one legal form is a provider block that declares only `alias`, which
+ * names a slot the caller fills through `providers = { aws.replica =
+ * aws.west }`. That is a declaration, not a configuration, so a block whose
+ * body has nothing but `alias` is not reported. Everything else is: a
+ * `region`, a `profile`, an `assume_role` block, and `version` too, which has
+ * been deprecated in favour of `required_providers` since Terraform 0.13.
+ */
+
+import type {
+  PostSynthCheck,
+  PostSynthContext,
+  PostSynthDiagnostic,
+} from "@intentius/chant/lint/post-synth";
+import { isResourceDeclarable } from "@intentius/chant/declarable";
+import { PROVIDER_TYPE, type BlockBody, type TerraformEntity } from "../../hcl/parse";
+import { isChildScoped } from "./scope";
+
+/** Everything in a provider body that is not the `alias` slot declaration. */
+function configuredKeys(body: BlockBody): string[] {
+  return Object.keys(body).filter((key) => key !== "alias");
+}
+
+export const tf014: PostSynthCheck = {
+  id: "TF014",
+  description: "Child module configures a provider block",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [key, entity] of ctx.entities) {
+      if (entity.entityType !== PROVIDER_TYPE || !isResourceDeclarable(entity)) continue;
+      if (!isChildScoped(entity)) continue;
+
+      const props = (entity as TerraformEntity).props as Partial<TerraformEntity["props"]>;
+      const body = (typeof props.body === "object" && props.body !== null ? props.body : {}) as BlockBody;
+      const configured = configuredKeys(body);
+      if (configured.length === 0) continue;
+
+      const address = typeof props.address === "string" ? props.address : key;
+      diagnostics.push({
+        checkId: "TF014",
+        severity: "warning",
+        message:
+          `Child module block "${address}" configures a provider (${configured.sort().join(", ")}). ` +
+          "A module that configures its own provider cannot be pointed at another region or account by " +
+          "its caller, cannot be called twice with different settings, and cannot be removed, since " +
+          "destroying its resources needs the provider configuration the removal deletes. Configure the " +
+          "provider in the root module and pass it in with `providers = { ... }`, leaving at most an " +
+          "`alias`-only block here.",
+        entity: key,
+        lexicon: "terraform",
+      });
+    }
+
+    return diagnostics;
+  },
+};

package/dist/rules/tf015.ts

@@ -0,0 +1,63 @@
+/**
+ * TF015: a `backend` or `cloud` block inside a child module.
+ *
+ * Scope: child modules only. This is TF001's mirror image. TF001 wants a root
+ * module to declare a backend, because a root without one keeps its state on
+ * local disk. A child module must declare neither: state belongs to the root,
+ * one state per root however many modules it calls, and Terraform says so
+ * directly, "A backend block can only appear in the root module" and the
+ * same for `cloud`. Depending on the version, the block is ignored with a
+ * warning or the root refuses to initialize, and either way the block is a
+ * claim about where state lives that the module does not get to make.
+ *
+ * The usual cause is a directory that used to be a root module and became a
+ * child when someone factored it out, with its `terraform` block carried
+ * along. The rest of that block is fine to keep: `required_version` and
+ * `required_providers` are meaningful in a child module and are not reported
+ * here.
+ */
+
+import type {
+  PostSynthCheck,
+  PostSynthContext,
+  PostSynthDiagnostic,
+} from "@intentius/chant/lint/post-synth";
+import { isResourceDeclarable } from "@intentius/chant/declarable";
+import { TERRAFORM_TYPE, type BlockBody, type TerraformEntity } from "../../hcl/parse";
+import { hasBlock } from "./tf001";
+import { isChildScoped } from "./scope";
+
+export const tf015: PostSynthCheck = {
+  id: "TF015",
+  description: "Child module declares a backend or cloud block",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [key, entity] of ctx.entities) {
+      if (entity.entityType !== TERRAFORM_TYPE || !isResourceDeclarable(entity)) continue;
+      if (!isChildScoped(entity)) continue;
+
+      const props = (entity as TerraformEntity).props as Partial<TerraformEntity["props"]>;
+      const body = (typeof props.body === "object" && props.body !== null ? props.body : {}) as BlockBody;
+      const backend = hasBlock(body, "backend");
+      const cloud = hasBlock(body, "cloud");
+      if (!backend && !cloud) continue;
+
+      const blockKind = backend ? "backend" : "cloud";
+      diagnostics.push({
+        checkId: "TF015",
+        severity: "warning",
+        message:
+          `A child module's terraform block declares a ${blockKind} block. Only a root module may: ` +
+          "state belongs to the root, one state file for every module it calls, so this block is either " +
+          `ignored with a warning or refused at init. Delete the ${blockKind} block and leave the state ` +
+          "configuration to the root module that calls this one.",
+        entity: key,
+        lexicon: "terraform",
+      });
+    }
+
+    return diagnostics;
+  },
+};

package/dist/rules/tf016.ts

@@ -0,0 +1,75 @@
+/**
+ * TF016: an attribute whose whole value is one quoted interpolation,
+ * `x = "${var.y}"`, the pre-0.12 style Terraform deprecated in 2019.
+ *
+ * The quotes buy nothing and cost readability: the expression is already an
+ * expression, and wrapping it in a template makes every value in the file look
+ * like a string whether it is one or not, which hides the actual type of an
+ * argument that takes a list or a bool.
+ *
+ * This is the one rule in the family that reads the block's SOURCE rather than
+ * its parsed body, and it has to. `@cdktf/hcl2json` renders both `x = var.y`
+ * and `x = "${var.y}"` as the string `"${var.y}"`, so a check over the parse
+ * cannot tell the deprecated form from the idiomatic one and would report every
+ * reference in the root. The quotes only survive in the text, so the text is
+ * what is scanned, one pass per file, through the same
+ * `interpolationOnlyLine` the deterministic fix uses, so the finding and the
+ * patch can never disagree.
+ *
+ * Out of reach, and deliberately not guessed at: tflint also reports the
+ * deprecated interpolation inside an object KEY (`"${var.k}" = "value"`).
+ * That is a different line shape and its fix is not a simple unquote, so this
+ * rule leaves it alone rather than emit a diff it cannot justify.
+ *
+ * Scope: root and child modules alike (#2112). The condition is a property
+ * of the block itself, so a descended module's block is read exactly as a
+ * root's is.
+ */
+
+import type {
+  PostSynthCheck,
+  PostSynthContext,
+  PostSynthDiagnostic,
+} from "@intentius/chant/lint/post-synth";
+import { isResourceDeclarable } from "@intentius/chant/declarable";
+import { interpolationOnlyLine } from "@intentius/chant/audit/proof";
+import type { TerraformEntity } from "../../hcl/parse";
+
+export const tf016: PostSynthCheck = {
+  id: "TF016",
+  description: "Attribute value is a quoted interpolation of a single expression",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+    /** `<root>/<file>` to that file's source, so a file is scanned once however many blocks it holds. */
+    const sources = new Map<string, string>();
+
+    for (const entity of ctx.entities.values()) {
+      if (entity.lexicon !== "terraform") continue;
+      if (!isResourceDeclarable(entity)) continue;
+      const props = (entity as TerraformEntity).props as Partial<TerraformEntity["props"]>;
+      if (typeof props.source !== "string" || props.source === "") continue;
+      sources.set(`${props.root ?? ""}/${props.file ?? ""}`, props.source);
+    }
+
+    for (const [key, source] of sources) {
+      const lines = source.split("\n");
+      for (let i = 0; i < lines.length; i++) {
+        const parsed = interpolationOnlyLine(lines[i]);
+        if (!parsed) continue;
+        diagnostics.push({
+          checkId: "TF016",
+          severity: "info",
+          message:
+            `${key}:${i + 1}: \`${parsed.name}\` wraps a single expression in a template ` +
+            `("\${${parsed.expr}}"). Terraform deprecated that spelling in 0.12. Write ` +
+            `\`${parsed.name} = ${parsed.expr}\` instead, so the argument keeps its own type.`,
+          entity: `${key}:${i + 1}`,
+          lexicon: "terraform",
+        });
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/dist/rules/tf017.ts

@@ -0,0 +1,50 @@
+/**
+ * TF017: a `module` block carries `depends_on`.
+ *
+ * `depends_on` on a module applies to every resource inside it, including the
+ * ones that had no reason to wait, so the whole module serializes behind the
+ * named dependency and a plan that could have run in parallel does not. It
+ * also makes the dependency invisible from inside the module, where the
+ * resource that actually needed the ordering lives.
+ *
+ * Passing an attribute of the dependency into a module input creates the same
+ * edge implicitly, only narrower and self-documenting.
+ *
+ * Scope: root and child modules alike (#2112). The condition is a property
+ * of the block itself, so a descended module's block is read exactly as a
+ * root's is.
+ */
+
+import type {
+  PostSynthCheck,
+  PostSynthContext,
+  PostSynthDiagnostic,
+} from "@intentius/chant/lint/post-synth";
+import { MODULE_TYPE } from "../../hcl/parse";
+import { blocksOfType } from "./blocks";
+
+export const tf017: PostSynthCheck = {
+  id: "TF017",
+  description: "Module block uses depends_on",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const block of blocksOfType(ctx, MODULE_TYPE)) {
+      if (!("depends_on" in block.body)) continue;
+
+      diagnostics.push({
+        checkId: "TF017",
+        severity: "info",
+        message:
+          `"${block.address}" uses \`depends_on\`, which orders every resource in the module behind ` +
+          "the dependency, not just the one that needs it. Pass an attribute of the dependency into " +
+          "a module input instead, so Terraform derives the edge itself.",
+        entity: block.key,
+        lexicon: "terraform",
+      });
+    }
+
+    return diagnostics;
+  },
+};