@intentius/chant-lexicon-k8s 0.0.12

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

@@ -0,0 +1,54 @@
+/**
+ * WK8204: RunAsNonRoot Recommended
+ *
+ * Containers should set securityContext.runAsNonRoot to true at either
+ * the container level or pod level. Running as root inside a container
+ * increases the blast radius of a container breakout.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput, parseK8sManifests, extractContainers, extractPodSpec, WORKLOAD_KINDS } from "./k8s-helpers";
+
+export const wk8204: PostSynthCheck = {
+  id: "WK8204",
+  description: "RunAsNonRoot recommended — running as root increases container breakout risk",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [, output] of ctx.outputs) {
+      const yaml = getPrimaryOutput(output);
+      const manifests = parseK8sManifests(yaml);
+
+      for (const manifest of manifests) {
+        if (!manifest.kind || !WORKLOAD_KINDS.has(manifest.kind)) continue;
+
+        const resourceName = manifest.metadata?.name ?? manifest.kind;
+        const podSpec = extractPodSpec(manifest);
+        if (!podSpec) continue;
+
+        // Check pod-level securityContext
+        const podSecCtx = podSpec.securityContext as Record<string, unknown> | undefined;
+        const podRunAsNonRoot = podSecCtx?.runAsNonRoot === true;
+
+        const containers = extractContainers(manifest);
+        for (const container of containers) {
+          const secCtx = container.securityContext;
+          const containerRunAsNonRoot = secCtx?.runAsNonRoot === true;
+
+          if (!podRunAsNonRoot && !containerRunAsNonRoot) {
+            diagnostics.push({
+              checkId: "WK8204",
+              severity: "warning",
+              message: `Container "${container.name ?? "(unnamed)"}" in ${manifest.kind} "${resourceName}" does not set runAsNonRoot: true — set it at container or pod level`,
+              entity: resourceName,
+              lexicon: "k8s",
+            });
+          }
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};

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

@@ -0,0 +1,56 @@
+/**
+ * WK8205: Drop ALL Capabilities
+ *
+ * Containers should drop all Linux capabilities and only add back those
+ * explicitly needed. This follows the principle of least privilege and
+ * reduces the attack surface.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput, parseK8sManifests, extractContainers, WORKLOAD_KINDS } from "./k8s-helpers";
+
+export const wk8205: PostSynthCheck = {
+  id: "WK8205",
+  description: "Drop ALL capabilities — containers should drop all capabilities and add only what is needed",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [, output] of ctx.outputs) {
+      const yaml = getPrimaryOutput(output);
+      const manifests = parseK8sManifests(yaml);
+
+      for (const manifest of manifests) {
+        if (!manifest.kind || !WORKLOAD_KINDS.has(manifest.kind)) continue;
+
+        const containers = extractContainers(manifest);
+        const resourceName = manifest.metadata?.name ?? manifest.kind;
+
+        for (const container of containers) {
+          const secCtx = container.securityContext;
+          const capabilities = secCtx?.capabilities as Record<string, unknown> | undefined;
+          const drop = capabilities?.drop;
+
+          const dropsAll =
+            Array.isArray(drop) &&
+            drop.some(
+              (cap) =>
+                (typeof cap === "string" && cap.toUpperCase() === "ALL"),
+            );
+
+          if (!dropsAll) {
+            diagnostics.push({
+              checkId: "WK8205",
+              severity: "warning",
+              message: `Container "${container.name ?? "(unnamed)"}" in ${manifest.kind} "${resourceName}" does not drop ALL capabilities — add securityContext.capabilities.drop: ["ALL"]`,
+              entity: resourceName,
+              lexicon: "k8s",
+            });
+          }
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};

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

@@ -0,0 +1,45 @@
+/**
+ * WK8207: No hostNetwork
+ *
+ * Pods should not use hostNetwork: true. Using the host network namespace
+ * bypasses network isolation and allows the pod to access all network
+ * interfaces on the host.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput, parseK8sManifests, extractPodSpec, WORKLOAD_KINDS } from "./k8s-helpers";
+
+export const wk8207: PostSynthCheck = {
+  id: "WK8207",
+  description: "No hostNetwork — using host network bypasses network isolation",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [, output] of ctx.outputs) {
+      const yaml = getPrimaryOutput(output);
+      const manifests = parseK8sManifests(yaml);
+
+      for (const manifest of manifests) {
+        if (!manifest.kind || !WORKLOAD_KINDS.has(manifest.kind)) continue;
+
+        const podSpec = extractPodSpec(manifest);
+        if (!podSpec) continue;
+
+        const resourceName = manifest.metadata?.name ?? manifest.kind;
+
+        if (podSpec.hostNetwork === true) {
+          diagnostics.push({
+            checkId: "WK8207",
+            severity: "warning",
+            message: `${manifest.kind} "${resourceName}" uses hostNetwork: true — this bypasses network isolation and should be avoided`,
+            entity: resourceName,
+            lexicon: "k8s",
+          });
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};

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

@@ -0,0 +1,45 @@
+/**
+ * WK8208: No hostPID
+ *
+ * Pods should not use hostPID: true. Sharing the host PID namespace
+ * allows the pod to see and interact with all processes on the host,
+ * which is a significant security risk.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput, parseK8sManifests, extractPodSpec, WORKLOAD_KINDS } from "./k8s-helpers";
+
+export const wk8208: PostSynthCheck = {
+  id: "WK8208",
+  description: "No hostPID — sharing host PID namespace allows visibility into all host processes",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [, output] of ctx.outputs) {
+      const yaml = getPrimaryOutput(output);
+      const manifests = parseK8sManifests(yaml);
+
+      for (const manifest of manifests) {
+        if (!manifest.kind || !WORKLOAD_KINDS.has(manifest.kind)) continue;
+
+        const podSpec = extractPodSpec(manifest);
+        if (!podSpec) continue;
+
+        const resourceName = manifest.metadata?.name ?? manifest.kind;
+
+        if (podSpec.hostPID === true) {
+          diagnostics.push({
+            checkId: "WK8208",
+            severity: "warning",
+            message: `${manifest.kind} "${resourceName}" uses hostPID: true — this allows visibility into all host processes and should be avoided`,
+            entity: resourceName,
+            lexicon: "k8s",
+          });
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};

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

@@ -0,0 +1,45 @@
+/**
+ * WK8209: No hostIPC
+ *
+ * Pods should not use hostIPC: true. Sharing the host IPC namespace
+ * allows the pod to access shared memory segments on the host, which
+ * can be used to escalate privileges or exfiltrate data.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput, parseK8sManifests, extractPodSpec, WORKLOAD_KINDS } from "./k8s-helpers";
+
+export const wk8209: PostSynthCheck = {
+  id: "WK8209",
+  description: "No hostIPC — sharing host IPC namespace can expose shared memory segments",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [, output] of ctx.outputs) {
+      const yaml = getPrimaryOutput(output);
+      const manifests = parseK8sManifests(yaml);
+
+      for (const manifest of manifests) {
+        if (!manifest.kind || !WORKLOAD_KINDS.has(manifest.kind)) continue;
+
+        const podSpec = extractPodSpec(manifest);
+        if (!podSpec) continue;
+
+        const resourceName = manifest.metadata?.name ?? manifest.kind;
+
+        if (podSpec.hostIPC === true) {
+          diagnostics.push({
+            checkId: "WK8209",
+            severity: "warning",
+            message: `${manifest.kind} "${resourceName}" uses hostIPC: true — this exposes host shared memory segments and should be avoided`,
+            entity: resourceName,
+            lexicon: "k8s",
+          });
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};

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

@@ -0,0 +1,51 @@
+/**
+ * WK8301: Probes Required
+ *
+ * Containers should have both livenessProbe and readinessProbe configured.
+ * Without probes, Kubernetes cannot detect unhealthy containers or know
+ * when a container is ready to receive traffic.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput, parseK8sManifests, extractContainers, WORKLOAD_KINDS } from "./k8s-helpers";
+
+export const wk8301: PostSynthCheck = {
+  id: "WK8301",
+  description: "Probes required — containers should have livenessProbe and readinessProbe",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [, output] of ctx.outputs) {
+      const yaml = getPrimaryOutput(output);
+      const manifests = parseK8sManifests(yaml);
+
+      for (const manifest of manifests) {
+        if (!manifest.kind || !WORKLOAD_KINDS.has(manifest.kind)) continue;
+        // CronJobs and Jobs are short-lived — probes are less relevant
+        if (manifest.kind === "Job" || manifest.kind === "CronJob") continue;
+
+        const containers = extractContainers(manifest);
+        const resourceName = manifest.metadata?.name ?? manifest.kind;
+
+        for (const container of containers) {
+          const missing: string[] = [];
+          if (!container.livenessProbe) missing.push("livenessProbe");
+          if (!container.readinessProbe) missing.push("readinessProbe");
+
+          if (missing.length > 0) {
+            diagnostics.push({
+              checkId: "WK8301",
+              severity: "warning",
+              message: `Container "${container.name ?? "(unnamed)"}" in ${manifest.kind} "${resourceName}" is missing ${missing.join(" and ")}`,
+              entity: resourceName,
+              lexicon: "k8s",
+            });
+          }
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};

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

@@ -0,0 +1,46 @@
+/**
+ * WK8302: Replicas >= 2 for High Availability
+ *
+ * Deployments should have at least 2 replicas for high availability.
+ * A single replica means any pod disruption causes downtime.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput, parseK8sManifests } from "./k8s-helpers";
+
+export const wk8302: PostSynthCheck = {
+  id: "WK8302",
+  description: "Replicas >= 2 recommended — single-replica Deployments have no high availability",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [, output] of ctx.outputs) {
+      const yaml = getPrimaryOutput(output);
+      const manifests = parseK8sManifests(yaml);
+
+      for (const manifest of manifests) {
+        if (manifest.kind !== "Deployment") continue;
+
+        const resourceName = manifest.metadata?.name ?? "Deployment";
+        const spec = manifest.spec;
+        if (!spec) continue;
+
+        const replicas = spec.replicas;
+
+        // If replicas is omitted, Kubernetes defaults to 1
+        if (replicas === undefined || replicas === null || replicas === 1) {
+          diagnostics.push({
+            checkId: "WK8302",
+            severity: "info",
+            message: `Deployment "${resourceName}" has ${replicas ?? 1} replica(s) — consider at least 2 for high availability`,
+            entity: resourceName,
+            lexicon: "k8s",
+          });
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};

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

@@ -0,0 +1,96 @@
+/**
+ * WK8303: PodDisruptionBudget Recommended for HA Deployments
+ *
+ * Deployments with 2 or more replicas should have a corresponding
+ * PodDisruptionBudget (PDB) to ensure minimum availability during
+ * voluntary disruptions like node drains and cluster upgrades.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput, parseK8sManifests } from "./k8s-helpers";
+import type { K8sManifest } from "./k8s-helpers";
+
+export const wk8303: PostSynthCheck = {
+  id: "WK8303",
+  description: "PDB recommended for HA Deployments — ensures availability during voluntary disruptions",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [, output] of ctx.outputs) {
+      const yaml = getPrimaryOutput(output);
+      const manifests = parseK8sManifests(yaml);
+
+      // Collect all PDB selectors to match against Deployments
+      const pdbSelectors = collectPdbSelectors(manifests);
+
+      for (const manifest of manifests) {
+        if (manifest.kind !== "Deployment") continue;
+
+        const spec = manifest.spec;
+        if (!spec) continue;
+
+        const replicas = spec.replicas;
+        // Only check HA deployments (replicas >= 2)
+        if (typeof replicas !== "number" || replicas < 2) continue;
+
+        const resourceName = manifest.metadata?.name ?? "Deployment";
+
+        // Check if any PDB targets this Deployment's labels
+        const selector = spec.selector as Record<string, unknown> | undefined;
+        const matchLabels = selector?.matchLabels as Record<string, string> | undefined;
+
+        if (!matchLabels || !hasCoveringPdb(matchLabels, pdbSelectors)) {
+          diagnostics.push({
+            checkId: "WK8303",
+            severity: "info",
+            message: `Deployment "${resourceName}" has ${replicas} replicas but no PodDisruptionBudget — add a PDB to ensure availability during voluntary disruptions`,
+            entity: resourceName,
+            lexicon: "k8s",
+          });
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};
+
+/**
+ * Collect matchLabels from all PodDisruptionBudget resources.
+ */
+function collectPdbSelectors(
+  manifests: K8sManifest[],
+): Array<Record<string, string>> {
+  const selectors: Array<Record<string, string>> = [];
+
+  for (const manifest of manifests) {
+    if (manifest.kind !== "PodDisruptionBudget") continue;
+
+    const spec = manifest.spec;
+    if (!spec) continue;
+
+    const selector = spec.selector as Record<string, unknown> | undefined;
+    const matchLabels = selector?.matchLabels as Record<string, string> | undefined;
+
+    if (matchLabels && typeof matchLabels === "object") {
+      selectors.push(matchLabels);
+    }
+  }
+
+  return selectors;
+}
+
+/**
+ * Check if any PDB selector covers (is a subset of) the given labels.
+ */
+function hasCoveringPdb(
+  deploymentLabels: Record<string, string>,
+  pdbSelectors: Array<Record<string, string>>,
+): boolean {
+  return pdbSelectors.some((pdbLabels) =>
+    Object.entries(pdbLabels).every(
+      ([key, value]) => deploymentLabels[key] === value,
+    ),
+  );
+}

package/src/lint/rules/hardcoded-namespace.ts

@@ -0,0 +1,56 @@
+import type { LintRule, LintDiagnostic, LintContext } from "@intentius/chant/lint/rule";
+import * as ts from "typescript";
+
+/**
+ * WK8001: Hardcoded Namespace
+ *
+ * Detects hardcoded namespace strings in Kubernetes resource constructors.
+ * Namespaces should be parameterized or derived from configuration, not
+ * hardcoded as string literals.
+ *
+ * Bad:  new Deployment({ metadata: { namespace: "production" } })
+ * Good: new Deployment({ metadata: { namespace: config.namespace } })
+ */
+export const hardcodedNamespaceRule: LintRule = {
+  id: "WK8001",
+  severity: "warning",
+  category: "correctness",
+  description:
+    "Detects hardcoded namespace strings — namespaces should be parameterized",
+
+  check(context: LintContext): LintDiagnostic[] {
+    const { sourceFile } = context;
+    const diagnostics: LintDiagnostic[] = [];
+
+    function visit(node: ts.Node): void {
+      // Look for property assignments like `namespace: "production"`
+      if (
+        ts.isPropertyAssignment(node) &&
+        ts.isIdentifier(node.name) &&
+        node.name.text === "namespace" &&
+        ts.isStringLiteral(node.initializer)
+      ) {
+        const value = node.initializer.text;
+        // Skip empty strings — those are likely intentional placeholders
+        if (value !== "") {
+          const { line, character } =
+            sourceFile.getLineAndCharacterOfPosition(
+              node.initializer.getStart(),
+            );
+          diagnostics.push({
+            file: sourceFile.fileName,
+            line: line + 1,
+            column: character + 1,
+            ruleId: "WK8001",
+            severity: "warning",
+            message: `Hardcoded namespace "${value}" detected. Use a variable or configuration parameter instead.`,
+          });
+        }
+      }
+      ts.forEachChild(node, visit);
+    }
+
+    visit(sourceFile);
+    return diagnostics;
+  },
+};

package/src/lint/rules/rules.test.ts

@@ -0,0 +1,69 @@
+import { describe, test, expect } from "bun:test";
+import { hardcodedNamespaceRule } from "./hardcoded-namespace";
+import * as ts from "typescript";
+
+function createContext(code: string) {
+  const sourceFile = ts.createSourceFile(
+    "test.ts",
+    code,
+    ts.ScriptTarget.Latest,
+    true,
+    ts.ScriptKind.TS,
+  );
+  return { sourceFile } as any;
+}
+
+describe("WK8001: Hardcoded Namespace", () => {
+  test("rule metadata", () => {
+    expect(hardcodedNamespaceRule.id).toBe("WK8001");
+    expect(hardcodedNamespaceRule.severity).toBe("warning");
+    expect(hardcodedNamespaceRule.category).toBe("correctness");
+  });
+
+  test("flags namespace: 'production' string literal", () => {
+    const ctx = createContext(
+      `new Deployment({ metadata: { namespace: "production" } });`,
+    );
+    const diags = hardcodedNamespaceRule.check(ctx);
+    expect(diags.length).toBe(1);
+    expect(diags[0].ruleId).toBe("WK8001");
+    expect(diags[0].message).toContain("production");
+  });
+
+  test("flags namespace: 'default' string literal", () => {
+    const ctx = createContext(
+      `new Deployment({ metadata: { namespace: "default" } });`,
+    );
+    const diags = hardcodedNamespaceRule.check(ctx);
+    expect(diags.length).toBe(1);
+    expect(diags[0].message).toContain("default");
+  });
+
+  test("does NOT flag namespace: myVar (variable reference)", () => {
+    const ctx = createContext(
+      `const ns = "production"; new Deployment({ metadata: { namespace: ns } });`,
+    );
+    const diags = hardcodedNamespaceRule.check(ctx);
+    // Only the string literal assignment to `namespace` key counts
+    // Variable references should not be flagged
+    const nsFlags = diags.filter((d) => d.ruleId === "WK8001");
+    expect(nsFlags.length).toBe(0);
+  });
+
+  test("does NOT flag empty namespace string", () => {
+    const ctx = createContext(
+      `new Deployment({ metadata: { namespace: "" } });`,
+    );
+    const diags = hardcodedNamespaceRule.check(ctx);
+    expect(diags.length).toBe(0);
+  });
+
+  test("flags multiple hardcoded namespaces", () => {
+    const ctx = createContext(`
+      const a = new Deployment({ metadata: { namespace: "staging" } });
+      const b = new Service({ metadata: { namespace: "prod" } });
+    `);
+    const diags = hardcodedNamespaceRule.check(ctx);
+    expect(diags.length).toBe(2);
+  });
+});

package/src/lsp/completions.test.ts

@@ -0,0 +1,64 @@
+import { describe, test, expect } from "bun:test";
+import { existsSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+
+const pkgDir = dirname(dirname(dirname(fileURLToPath(import.meta.url))));
+const hasGenerated = existsSync(
+  join(pkgDir, "src", "generated", "lexicon-k8s.json"),
+);
+
+describe("LSP completions", () => {
+  test.skipIf(!hasGenerated)(
+    "returns completions for 'new D' prefix",
+    async () => {
+      const { k8sCompletions } = await import("./completions");
+      const result = k8sCompletions({
+        uri: "file:///test.ts",
+        content: "const x = new D",
+        linePrefix: "const x = new D",
+        wordAtCursor: "D",
+        position: { line: 0, character: 15 },
+      } as any);
+
+      expect(result).toBeDefined();
+      expect(Array.isArray(result)).toBe(true);
+      const labels = result.map((c: any) => c.label ?? c);
+      expect(labels.some((l: string) => l.includes("Deployment"))).toBe(true);
+    },
+  );
+
+  test.skipIf(!hasGenerated)(
+    "returns empty for non-constructor context",
+    async () => {
+      const { k8sCompletions } = await import("./completions");
+      const result = k8sCompletions({
+        uri: "file:///test.ts",
+        content: "const x = 42",
+        linePrefix: "const x = 42",
+        wordAtCursor: "",
+        position: { line: 0, character: 12 },
+      } as any);
+
+      expect(Array.isArray(result)).toBe(true);
+      expect(result.length).toBe(0);
+    },
+  );
+
+  test.skipIf(!hasGenerated)("filters by prefix correctly", async () => {
+    const { k8sCompletions } = await import("./completions");
+    const result = k8sCompletions({
+      uri: "file:///test.ts",
+      content: "const x = new StatefulS",
+      linePrefix: "const x = new StatefulS",
+      wordAtCursor: "StatefulS",
+      position: { line: 0, character: 23 },
+    } as any);
+
+    expect(Array.isArray(result)).toBe(true);
+    if (result.length > 0) {
+      const labels = result.map((c: any) => c.label ?? c);
+      expect(labels.some((l: string) => l.includes("StatefulSet"))).toBe(true);
+    }
+  });
+});

package/src/lsp/completions.ts

@@ -0,0 +1,20 @@
+import { createRequire } from "module";
+import type { CompletionContext, CompletionItem } from "@intentius/chant/lsp/types";
+import { LexiconIndex, lexiconCompletions, type LexiconEntry } from "@intentius/chant/lsp/lexicon-providers";
+const require = createRequire(import.meta.url);
+
+let cachedIndex: LexiconIndex | null = null;
+
+function getIndex(): LexiconIndex {
+  if (cachedIndex) return cachedIndex;
+  const data = require("../generated/lexicon-k8s.json") as Record<string, LexiconEntry>;
+  cachedIndex = new LexiconIndex(data);
+  return cachedIndex;
+}
+
+/**
+ * Provide Kubernetes resource completions based on context.
+ */
+export function k8sCompletions(ctx: CompletionContext): CompletionItem[] {
+  return lexiconCompletions(ctx, getIndex(), "Kubernetes resource");
+}