@intentius/chant 0.5.0 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Declarative infrastructure-as-code toolkit — TypeScript on Node.js",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",

package/src/audit/catalog.test.ts

@@ -4,7 +4,7 @@ import { loadPlugins } from "../cli/plugins";
 
 /** All post-synth check ids the audit can actually surface, from the lexicons. */
 async function realCheckIds(): Promise<Set<string>> {
-  const plugins = await loadPlugins(["github", "gitlab", "forgejo"]);
+  const plugins = await loadPlugins(["github", "gitlab", "forgejo", "k8s", "docker"]);
   const ids = new Set<string>();
   for (const plugin of plugins) {
     for (const check of plugin.postSynthChecks?.() ?? []) {

package/src/audit/catalog.ts

@@ -74,6 +74,18 @@ const GH_OIDC: Authority = {
   name: "GitHub — Security hardening with OpenID Connect",
   url: "https://docs.github.com/en/actions/concepts/security/openid-connect",
 };
+const K8S_PSS: Authority = {
+  name: "Kubernetes — Pod Security Standards",
+  url: "https://kubernetes.io/docs/concepts/security/pod-security-standards/",
+};
+const K8S_SECRETS: Authority = {
+  name: "Kubernetes — Good practices for Secrets",
+  url: "https://kubernetes.io/docs/concepts/security/secrets-good-practices/",
+};
+const DOCKER_SEC: Authority = {
+  name: "Docker — Security best practices",
+  url: "https://docs.docker.com/develop/security-best-practices/",
+};
 
 function meta(
   id: string,
@@ -184,6 +196,45 @@ export const RULE_CATALOG: Record<string, RuleMeta> = {
   // ── Forgejo (WFJ) ──────────────────────────────────────────────────
   WFJ010: meta("WFJ010", M, G, "Unresolved action reference on Forgejo", "Use an action reference Forgejo can resolve (full URL or a mirrored action)."),
   WFJ011: meta("WFJ011", M, G, "GitHub-hosted runner label with no Forgejo equivalent", "Use a runner label your Forgejo instance provides."),
+
+  // ── Kubernetes (WK8 / ARGO) ────────────────────────────────────────
+  ARGO002: meta("ARGO002", M, G, "Argo Application references an undeclared AppProject", "Declare the named AppProject or reference an existing project."),
+  ARGO003: meta("ARGO003", M, G, "Argo Application targets an unregistered cluster", "Point spec.destination at a registered cluster or the in-cluster target."),
+  ARGO005: meta("ARGO005", R, G, "Argo source.path may not resolve", "Ensure the source path exists under the build root."),
+  WK8005: meta("WK8005", M, G, "Hardcoded secret in env var", "Use a secretKeyRef instead of a literal value, and rotate the secret.", [K8S_SECRETS]),
+  WK8006: meta("WK8006", M, G, "Image uses :latest or no tag", "Pin the image to an explicit version tag (ideally a digest).", [SCORECARD_PINNED]),
+  WK8041: meta("WK8041", M, G, "Hardcoded API key in env var", "Move the key to a Secret and rotate it.", [K8S_SECRETS]),
+  WK8042: meta("WK8042", M, G, "Private key stored in a ConfigMap", "Store private keys in a Secret, not a ConfigMap.", [K8S_SECRETS]),
+  WK8101: meta("WK8101", M, G, "Deployment selector does not match template labels", "Align spec.selector with the pod template labels."),
+  WK8102: meta("WK8102", R, G, "Resource missing metadata labels", "Add metadata labels for filtering and tooling."),
+  WK8103: meta("WK8103", M, G, "Container missing name", "Add the required container `name`."),
+  WK8104: meta("WK8104", R, G, "Container ports not named", "Name ports for clearer Service/NetworkPolicy config."),
+  WK8105: meta("WK8105", R, G, "imagePullPolicy not explicit", "Set imagePullPolicy explicitly to avoid surprising defaults."),
+  WK8201: meta("WK8201", R, G, "Container missing resource limits", "Set CPU and memory limits."),
+  WK8202: meta("WK8202", M, G, "Privileged container", "Remove privileged: true; grant only the specific capabilities needed.", [K8S_PSS]),
+  WK8203: meta("WK8203", M, G, "Root filesystem is writable", "Set readOnlyRootFilesystem: true.", [K8S_PSS]),
+  WK8204: meta("WK8204", M, G, "Container may run as root", "Set runAsNonRoot: true (and a non-zero runAsUser).", [K8S_PSS]),
+  WK8205: meta("WK8205", M, G, "Capabilities not dropped", "drop: [ALL] and add back only what is required.", [K8S_PSS]),
+  WK8207: meta("WK8207", M, G, "Pod uses host network", "Remove hostNetwork; it bypasses network isolation.", [K8S_PSS]),
+  WK8208: meta("WK8208", M, G, "Pod shares host PID namespace", "Remove hostPID.", [K8S_PSS]),
+  WK8209: meta("WK8209", M, G, "Pod shares host IPC namespace", "Remove hostIPC.", [K8S_PSS]),
+  WK8301: meta("WK8301", R, G, "Container missing probes", "Add liveness and readiness probes."),
+  WK8302: meta("WK8302", R, G, "Deployment has a single replica", "Use replicas >= 2 for availability."),
+  WK8303: meta("WK8303", R, G, "No PodDisruptionBudget for an HA Deployment", "Add a PDB to protect availability during disruptions."),
+  WK8304: meta("WK8304", R, G, "SSL redirect without a certificate", "Provide a certificate and HTTPS listen-ports for the ssl-redirect annotation."),
+  WK8305: meta("WK8305", M, G, "Ingress backend port does not match the Service", "Point the Ingress backend at a declared Service port."),
+  WK8306: meta("WK8306", M, G, "Container command starts with a flag", "The first command element should be a binary, not a flag."),
+  WK8401: meta("WK8401", M, G, "shmSize exceeds the container memory limit", "Lower shmSize or raise the memory limit so the pod can schedule."),
+  WK8402: meta("WK8402", R, G, "RayCluster missing spec.rayVersion", "Set spec.rayVersion so KubeRay picks the right autoscaler image."),
+  WK8403: meta("WK8403", R, G, "rayVersion does not match the head image tag", "Align spec.rayVersion with the Ray version in the head container image."),
+
+  // ── Docker (DKRD) ──────────────────────────────────────────────────
+  DKRD001: meta("DKRD001", M, G, "Service uses :latest or untagged image", "Pin the image to an explicit version tag (ideally a digest).", [SCORECARD_PINNED]),
+  DKRD002: meta("DKRD002", R, G, "Named volume declared but unused", "Remove the unused volume or mount it in a service."),
+  DKRD003: meta("DKRD003", M, G, "Service exposes SSH (port 22)", "Don't expose SSH from a container; use exec/ephemeral access instead.", [DOCKER_SEC]),
+  DKRD010: meta("DKRD010", R, G, "apt-get install without --no-install-recommends", "Add --no-install-recommends to keep images small."),
+  DKRD011: meta("DKRD011", R, G, "ADD used where COPY would do", "Prefer COPY unless fetching a URL or extracting an archive."),
+  DKRD012: meta("DKRD012", M, G, "No USER instruction — container runs as root", "Add a non-root USER instruction.", [DOCKER_SEC]),
 };
 
 /** Look up catalog metadata for a check id, if known. */

package/src/audit/core.test.ts

@@ -1,7 +1,27 @@
 import { describe, test, expect } from "vitest";
-import { auditFiles, type AuditInput } from "./core";
+import { auditFiles, CROSS_FILE, type AuditInput } from "./core";
 import type { PostSynthCheck } from "../lint/post-synth";
 
+const ARGO_APP = `apiVersion: argoproj.io/v1alpha1
+kind: Application
+metadata:
+  name: myapp
+spec:
+  project: team-a
+  source:
+    repoURL: https://example.com/repo
+    path: .
+  destination:
+    server: https://kubernetes.default.svc
+    namespace: default
+`;
+const ARGO_PROJECT = `apiVersion: argoproj.io/v1alpha1
+kind: AppProject
+metadata:
+  name: team-a
+`;
+const WF = (name: string) => `name: ${name}\non:\n  push:\njobs:\n  build:\n    runs-on: ubuntu-latest\n`;
+
 const DIRTY_GH = `name: CI
 on:
   push:
@@ -108,6 +128,32 @@ describe("auditFiles", () => {
     expect(findings.map((f) => f.file).sort()).toEqual(["a.yml", "b.yml"]);
   });
 
+  test("resolves a cross-file relationship (ARGO002 sees the AppProject in another file)", async () => {
+    // The Application alone → ARGO002 fires (project not declared here).
+    const alone = await auditFiles([{ path: "app.yaml", content: ARGO_APP, lexicon: "k8s" }]);
+    expect(alone.some((f) => f.checkId === "ARGO002")).toBe(true);
+
+    // With the AppProject in a separate file → ARGO002 must NOT fire.
+    const together = await auditFiles([
+      { path: "app.yaml", content: ARGO_APP, lexicon: "k8s" },
+      { path: "project.yaml", content: ARGO_PROJECT, lexicon: "k8s" },
+    ]);
+    expect(together.some((f) => f.checkId === "ARGO002")).toBe(false);
+  });
+
+  test("surfaces a genuine cross-file finding (GHA006 duplicate workflow name)", async () => {
+    const findings = await auditFiles([
+      { path: ".github/workflows/a.yml", content: WF("CI"), lexicon: "github" },
+      { path: ".github/workflows/b.yml", content: WF("CI"), lexicon: "github" },
+    ]);
+    const dup = findings.find((f) => f.checkId === "GHA006");
+    expect(dup).toBeDefined();
+    expect(dup!.file).toBe(CROSS_FILE);
+    // A single workflow → no duplicate finding.
+    const single = await auditFiles([{ path: "a.yml", content: WF("CI"), lexicon: "github" }]);
+    expect(single.some((f) => f.checkId === "GHA006")).toBe(false);
+  });
+
   test("a check that throws does not abort the audit", async () => {
     const boom: PostSynthCheck = {
       id: "BOOM",

package/src/audit/rules-doc.ts

@@ -9,10 +9,12 @@
 
 import { RULE_CATALOG, type RuleMeta } from "./catalog";
 
-const GROUPS: Array<{ heading: string; prefix: string; blurb: string }> = [
-  { heading: "GitHub Actions (GHA)", prefix: "GHA", blurb: "Also applied to Forgejo workflows, which are GitHub-dialect." },
-  { heading: "GitLab CI (WGL)", prefix: "WGL", blurb: "" },
-  { heading: "Forgejo (WFJ)", prefix: "WFJ", blurb: "" },
+const GROUPS: Array<{ heading: string; prefixes: string[]; blurb: string }> = [
+  { heading: "GitHub Actions (GHA)", prefixes: ["GHA"], blurb: "Also applied to Forgejo workflows, which are GitHub-dialect." },
+  { heading: "GitLab CI (WGL)", prefixes: ["WGL"], blurb: "" },
+  { heading: "Forgejo (WFJ)", prefixes: ["WFJ"], blurb: "" },
+  { heading: "Kubernetes (WK8 / ARGO)", prefixes: ["WK8", "ARGO"], blurb: "Run against Kubernetes manifests." },
+  { heading: "Docker (DKRD)", prefixes: ["DKRD"], blurb: "Run against Dockerfiles and Compose files." },
 ];
 
 function ruleBlock(m: RuleMeta): string {
@@ -26,8 +28,8 @@ function ruleBlock(m: RuleMeta): string {
 /** Render the full audit rules reference page (frontmatter + body). */
 export function renderRulesReference(): string {
   const ids = Object.keys(RULE_CATALOG).sort();
-  const sections = GROUPS.map(({ heading, prefix, blurb }) => {
-    const blocks = ids.filter((id) => id.startsWith(prefix)).map((id) => ruleBlock(RULE_CATALOG[id]));
+  const sections = GROUPS.map(({ heading, prefixes, blurb }) => {
+    const blocks = ids.filter((id) => prefixes.some((p) => id.startsWith(p))).map((id) => ruleBlock(RULE_CATALOG[id]));
     if (blocks.length === 0) return "";
     return `## ${heading}\n${blurb ? `\n${blurb}\n` : ""}\n${blocks.join("\n\n")}`;
   }).filter(Boolean);

package/src/cli/commands/__fixtures__/audit-docker/app/Dockerfile

@@ -0,0 +1,4 @@
+FROM node:20
+RUN apt-get update && apt-get install -y curl
+COPY . /app
+CMD ["node", "server.js"]

package/src/cli/commands/__fixtures__/audit-docker/docker-compose.yml

@@ -0,0 +1,5 @@
+services:
+  web:
+    image: myapp:latest
+    ports:
+      - "22:22"

package/src/cli/commands/__fixtures__/audit-k8s/manifests/deploy.yaml

@@ -0,0 +1,18 @@
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: web
+spec:
+  selector:
+    matchLabels:
+      app: web
+  template:
+    metadata:
+      labels:
+        app: web
+    spec:
+      containers:
+        - name: web
+          image: nginx:latest
+          securityContext:
+            privileged: true

package/src/cli/commands/audit.test.ts

@@ -1,6 +1,6 @@
 import { describe, test, expect } from "vitest";
 import { fileURLToPath } from "url";
-import { auditCommand, discoverCiFiles, tokenForHost, coverageNotes } from "./audit";
+import { auditCommand, discoverCiFiles, discoverManifests, discoverDocker, tokenForHost, coverageNotes } from "./audit";
 import { MissingLexiconError, type AuditInput } from "../../audit/core";
 import { readFileSync, existsSync, rmSync } from "fs";
 import { tmpdir } from "os";
@@ -30,6 +30,34 @@ describe("auditCommand", () => {
     expect(coverageNotes(gh)).toEqual([]);
   });
 
+  test("discovers and audits Kubernetes manifests", async () => {
+    const repo = fileURLToPath(new URL("./__fixtures__/audit-k8s", import.meta.url));
+    const files = discoverManifests(repo);
+    expect(files.map((f) => f.path)).toContain("manifests/deploy.yaml");
+    expect(files.every((f) => f.lexicon === "k8s")).toBe(true);
+
+    const result = await auditCommand({ path: repo, format: "stylish" });
+    expect(result.success).toBe(true);
+    const ids = new Set(result.findings.map((f) => f.checkId));
+    expect(ids).toContain("WK8202"); // privileged container
+    expect(ids).toContain("WK8006"); // :latest image
+  });
+
+  test("discovers and audits Docker artifacts (nested Dockerfile + compose)", async () => {
+    const repo = fileURLToPath(new URL("./__fixtures__/audit-docker", import.meta.url));
+    const files = discoverDocker(repo);
+    const paths = files.map((f) => f.path).sort();
+    expect(paths).toContain("app/Dockerfile");
+    expect(paths).toContain("docker-compose.yml");
+
+    const result = await auditCommand({ path: repo, format: "stylish" });
+    expect(result.success).toBe(true);
+    const ids = new Set(result.findings.map((f) => f.checkId));
+    expect(ids).toContain("DKRD012"); // Dockerfile has no USER (nested — basename-key fix)
+    expect(ids).toContain("DKRD010"); // apt-get without --no-install-recommends
+    expect(ids).toContain("DKRD003"); // compose exposes SSH port 22
+  });
+
   test("discovers CI files under a repo root", () => {
     const files = discoverCiFiles(REPO);
     expect(files.map((f) => f.path)).toContain(".github/workflows/ci.yml");
@@ -99,11 +127,14 @@ describe("auditCommand", () => {
   });
 
   test("a path with no CI files succeeds with a clear message", async () => {
-    const tmp = fileURLToPath(new URL(".", import.meta.url)); // commands dir, no CI files
+    const tmp = join(tmpdir(), `chant-audit-empty-${process.pid}`);
+    const { mkdirSync } = await import("fs");
+    mkdirSync(tmp, { recursive: true });
     const result = await auditCommand({ path: tmp });
     expect(result.success).toBe(true);
     expect(result.exitCode).toBe(0);
     expect(result.output).toContain("No CI files found");
+    rmSync(tmp, { recursive: true, force: true });
   });
 
   test("audits a remote repo URL via injected fetch", async () => {

package/src/cli/commands/audit.ts

@@ -6,7 +6,8 @@
  */
 
 import { existsSync, readFileSync, readdirSync, statSync, writeFileSync } from "fs";
-import { join, relative } from "path";
+import { join, relative, basename } from "path";
+import { parseYAML } from "../../yaml";
 import { auditFiles, type AuditInput, type AuditFinding, type AuditLexicon, type ChecksProvider } from "../../audit/core";
 import { RULE_CATALOG } from "../../audit/catalog";
 import { renderMarkdown } from "../../audit/report";
@@ -115,6 +116,95 @@ export function discoverCiFiles(root: string): AuditInput[] {
   return inputs;
 }
 
+const WALK_SKIP = new Set(["node_modules", ".git", "dist", ".github", ".forgejo"]);
+const MAX_WALK_FILES = 1000;
+
+/** Recursively collect file paths under a root, skipping noise/dot dirs. */
+function walkFiles(dir: string, out: string[]): void {
+  if (out.length >= MAX_WALK_FILES) return;
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const e of entries.sort((a, b) => (a.name < b.name ? -1 : 1))) {
+    if (out.length >= MAX_WALK_FILES) return;
+    if (e.name.startsWith(".") && e.isDirectory()) continue;
+    if (WALK_SKIP.has(e.name)) continue;
+    const full = join(dir, e.name);
+    if (e.isDirectory()) walkFiles(full, out);
+    else out.push(full);
+  }
+}
+
+function readSafe(full: string): string | undefined {
+  try {
+    return readFileSync(full, "utf-8");
+  } catch {
+    return undefined;
+  }
+}
+
+/** True if any YAML document in the content is a Kubernetes manifest. */
+function looksLikeK8s(content: string): boolean {
+  for (const doc of content.split(/\n---\n/)) {
+    const t = doc.trim();
+    if (!t) continue;
+    try {
+      const obj = parseYAML(t) as Record<string, unknown>;
+      if (obj && typeof obj.apiVersion === "string" && typeof obj.kind === "string") return true;
+    } catch {
+      // not parseable as a single doc — skip
+    }
+  }
+  return false;
+}
+
+/** Discover Kubernetes manifest files under a repo root (content-detected). */
+export function discoverManifests(root: string): AuditInput[] {
+  const files: string[] = [];
+  walkFiles(root, files);
+  const inputs: AuditInput[] = [];
+  for (const full of files) {
+    if (!isYaml(basename(full))) continue;
+    const content = readSafe(full);
+    if (content !== undefined && looksLikeK8s(content)) {
+      inputs.push({ path: relative(root, full), content, lexicon: "k8s" });
+    }
+  }
+  return inputs;
+}
+
+function isDockerfileName(name: string): boolean {
+  return name === "Dockerfile" || name.startsWith("Dockerfile.") || name.endsWith(".Dockerfile") || name.endsWith(".dockerfile");
+}
+
+function looksLikeCompose(content: string): boolean {
+  try {
+    const obj = parseYAML(content) as Record<string, unknown>;
+    return Boolean(obj) && typeof obj === "object" && "services" in obj;
+  } catch {
+    return false;
+  }
+}
+
+/** Discover Docker artifacts: Dockerfiles (by name) and Compose files (by `services:`). */
+export function discoverDocker(root: string): AuditInput[] {
+  const files: string[] = [];
+  walkFiles(root, files);
+  const inputs: AuditInput[] = [];
+  for (const full of files) {
+    const name = basename(full);
+    const content = readSafe(full);
+    if (content === undefined) continue;
+    if (isDockerfileName(name) || (isYaml(name) && looksLikeCompose(content))) {
+      inputs.push({ path: relative(root, full), content, lexicon: "docker" });
+    }
+  }
+  return inputs;
+}
+
 function isMergeWorthy(f: AuditFinding): boolean {
   return RULE_CATALOG[f.checkId]?.tier === "merge-worthy";
 }
@@ -247,7 +337,7 @@ export async function auditCommand(options: AuditCommandOptions): Promise<AuditC
     if (!existsSync(options.path)) {
       return { success: false, output: "", findings: [], scanned: [], exitCode: 1, error: `Path not found: ${options.path}` };
     }
-    inputs = discoverCiFiles(options.path);
+    inputs = [...discoverCiFiles(options.path), ...discoverManifests(options.path), ...discoverDocker(options.path)];
   }
 
   const scanned = inputs.map((i) => i.path);