@intentius/chant 0.57.0 → 0.59.0

package/src/audit/discover.ts

@@ -21,6 +21,12 @@
  *     `detectTemplate` (which only knows Compose's `services:`) can't see them.
  *   - Helm charts are a directory BUNDLE keyed by `Chart.yaml`; the helm checks
  *     read `output.files`, so the whole chart is one AuditInput.
+ *   - Terraform is also a directory BUNDLE, keyed by that directory's own
+ *     `.tf` filenames, not recursively: a nested directory with its own
+ *     `.tf` files (e.g. `modules/foo`) is its own AuditInput, UNLESS another
+ *     directory's `.tf` calls it as a local module, in which case it is a
+ *     child module of that root and is parsed as part of it (#2217). `.tf`
+ *     isn't YAML/JSON either, so `detectTemplate` can't see it.
  *   - k8s `detectTemplate` matches any `apiVersion`+`kind`, including GCP Config
  *     Connector (`cnrm.cloud.google.com`) resources and fountain
  *     (`fountain.dev/v1`) manifests, so gcp and fountain must be tried first.
@@ -29,14 +35,15 @@
  */
 
 import { readdirSync, readFileSync, statSync } from "fs";
-import { basename, join, relative } from "path";
+import { basename, join, relative, resolve } from "path";
 import { parseYAML } from "../yaml";
 import type { LexiconPlugin } from "../lexicon";
 import type { AuditInput, AuditLexicon } from "./core";
 import { isNginxConfigPath } from "./nginx";
+import { gitignoreCoversTerraformState, isTerraformStatePath } from "./terraform-state";
 
 /** Lexicons the auditor knows how to detect and run checks for. */
-export const AUDIT_LEXICONS = ["github", "gitlab", "forgejo", "k8s", "docker", "aws", "azure", "gcp", "helm", "fountain"] as const;
+export const AUDIT_LEXICONS = ["github", "gitlab", "forgejo", "k8s", "docker", "aws", "azure", "gcp", "helm", "fountain", "terraform"] as const;
 
 /**
  * Load the plugins used for detection. Each is loaded in isolation (no
@@ -63,6 +70,8 @@ export async function loadAuditPlugins(names: readonly string[] = AUDIT_LEXICONS
 }
 
 const WALK_SKIP = new Set(["node_modules", ".git", "dist"]);
+/** Terraform's local working directory: recorded by the walk, never entered (TF023). */
+const TERRAFORM_WORK_DIR = ".terraform";
 /** Dot-directories the walk descends into anyway (CI lives here). */
 const WALK_DOT_DIRS = new Set([".github", ".forgejo"]);
 const MAX_WALK_FILES = 1000;
@@ -80,7 +89,15 @@ function walkFiles(dir: string, out: string[]): void {
   }
   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() && !WALK_DOT_DIRS.has(e.name)) continue;
+    if (e.name.startsWith(".") && e.isDirectory() && !WALK_DOT_DIRS.has(e.name)) {
+      // `.terraform/` is never descended into: it is machine-generated,
+      // routinely hundreds of megabytes of provider binaries, and nothing in
+      // it is worth reading. Its presence is itself the finding (TF023), so
+      // the directory path alone is recorded and `collectCandidates` hands it
+      // on with no content.
+      if (e.name === TERRAFORM_WORK_DIR) out.push(join(dir, e.name));
+      continue;
+    }
     if (WALK_SKIP.has(e.name)) continue;
     const full = join(dir, e.name);
     if (e.isDirectory()) walkFiles(full, out);
@@ -105,6 +122,10 @@ function isDockerfileName(name: string): boolean {
   return name === "Dockerfile" || name.startsWith("Dockerfile.") || name.endsWith(".Dockerfile") || name.endsWith(".dockerfile");
 }
 
+function isTerraformFileName(name: string): boolean {
+  return /\.tf$/i.test(name);
+}
+
 /**
  * Filenames the secrets scan (#443) wants that no lexicon otherwise reads —
  * dotenv files and key/cert material. Included in `isCandidatePath` so both
@@ -294,11 +315,11 @@ export function isCandidatePath(path: string): boolean {
  * (path, filename, a few content markers) with no lexicon plugin involved.
  * Names the lexicon that would have claimed a file when that lexicon isn't
  * installed (#1623). Deliberately coarse: precision comes from the plugin's
- * `detectTemplate`, which is exactly what's missing in that case.
- * `terraform` is not an audit lexicon; `*.tf` is surfaced so the user learns
- * the audit never reads it (see `chant carve`).
+ * `detectTemplate`, which is exactly what's missing in that case. `terraform`
+ * is a lexicon like any other here: a `.tf` file hints at it by name, the
+ * same way `Chart.yaml` hints at helm.
  */
-export type LexiconHint = AuditLexicon | "terraform";
+export type LexiconHint = AuditLexicon;
 
 export function hintLexiconForFile(path: string, content: string): LexiconHint | undefined {
   const name = basename(path);
@@ -306,7 +327,7 @@ export function hintLexiconForFile(path: string, content: string): LexiconHint |
   if (ci) return ci;
   if (isDockerfileName(name)) return "docker";
   if (name === "Chart.yaml") return "helm";
-  if (/\.tf$/i.test(name)) return "terraform";
+  if (isTerraformFileName(name)) return "terraform";
   const head = content.slice(0, 64 * 1024);
   if (/cnrm\.cloud\.google\.com/.test(head)) return "gcp";
   if (/fountain\.dev\/v1/.test(head)) return "fountain";
@@ -371,25 +392,175 @@ function classifyHelm(files: RepoFile[], plugin: DetectPlugin | undefined): { in
   return { inputs, prefixes };
 }
 
+/**
+ * A `source` attribute naming a local path, the only module source Terraform
+ * reads from the repository itself. A registry or git source ("hashicorp/aws",
+ * "git::https://...") never starts with `./` or `../`, and `source` inside
+ * `required_providers` is a registry address, so the prefix is what tells the
+ * two apart without an HCL parser here. `classifyTerraform` uses this to tell
+ * a root module from a directory that is somebody's child module; the lexicon
+ * plugin parses the calls properly once it has the root.
+ */
+const LOCAL_MODULE_SOURCE = /(?:^|[\s{,])source\s*=\s*"(\.{1,2}\/[^"]*)"/g;
+
+/**
+ * Resolve `rel` against the repo-relative directory `dir`. Returns undefined
+ * when the path climbs above the audited root, which is a directory this walk
+ * never read and so can never be one of its inputs.
+ */
+function resolveRepoDir(dir: string, rel: string): string | undefined {
+  const parts = dir === "" ? [] : dir.split("/");
+  for (const segment of rel.split("/")) {
+    if (segment === "" || segment === ".") continue;
+    if (segment === "..") {
+      if (parts.length === 0) return undefined;
+      parts.pop();
+      continue;
+    }
+    parts.push(segment);
+  }
+  return parts.join("/");
+}
+
+/**
+ * The directories that are somebody's local child module: a `.tf` file in
+ * another directory of this walk calls them with a relative `source`.
+ *
+ * They are dropped as audit inputs of their own, because the root that calls
+ * them parses them as child scopes (the terraform plugin's `auditEntities`
+ * descends from `AuditInput.dir`, #2217). Auditing them twice would report
+ * every finding in them twice, once per scope, and auditing them as roots is
+ * what made `chant audit` disagree with `chant build` about which rules apply
+ * to a child module at all.
+ *
+ * A directory a cycle reaches but no root does is kept: `a` calling `b`
+ * calling `a` is a configuration Terraform refuses, and dropping both would
+ * leave the files audited by nothing.
+ */
+function calledAsLocalModule(byDir: Map<string, Record<string, string>>): Set<string> {
+  const callees = new Map<string, Set<string>>();
+  const called = new Set<string>();
+  for (const [dir, bundle] of byDir) {
+    const targets = new Set<string>();
+    for (const source of Object.values(bundle)) {
+      for (const match of source.matchAll(LOCAL_MODULE_SOURCE)) {
+        const target = resolveRepoDir(dir, match[1]);
+        if (target === undefined || target === dir || !byDir.has(target)) continue;
+        targets.add(target);
+        called.add(target);
+      }
+    }
+    callees.set(dir, targets);
+  }
+
+  const queue = [...byDir.keys()].filter((dir) => !called.has(dir));
+  const reached = new Set<string>(queue);
+  while (queue.length > 0) {
+    for (const target of callees.get(queue.shift()!) ?? []) {
+      if (reached.has(target)) continue;
+      reached.add(target);
+      queue.push(target);
+    }
+  }
+  return new Set([...called].filter((dir) => reached.has(dir)));
+}
+
+/**
+ * Collect Terraform root modules as directory bundles from an in-memory file
+ * set, modeled on `classifyHelm`. Unlike a Helm chart (its whole subtree is
+ * one bundle), a Terraform root module references only its own sibling
+ * files, so grouping is by each `.tf` file's immediate directory, not
+ * recursive.
+ *
+ * A directory another one calls as a local module is not a root module and
+ * gets no input of its own (#2217): the root that calls it parses it as a
+ * child scope, which is what Terraform does and what `chant build` already
+ * did. That descent reads the child's directory from disk, so it only happens
+ * when `baseDir` says a local walk found these files; an in-memory file set
+ * with no directory behind it keeps every `.tf` directory as its own input,
+ * as before.
+ *
+ * Returns inputs plus the exact `.tf` paths claimed, so the loose-file pass in
+ * `classifyFiles` can skip them — a child module's files are claimed too, by
+ * the root that will parse them.
+ */
+function classifyTerraform(
+  files: RepoFile[],
+  plugin: DetectPlugin | undefined,
+  baseDir?: string,
+): { inputs: AuditInput[]; claimed: Set<string> } {
+  const inputs: AuditInput[] = [];
+  const claimed = new Set<string>();
+  if (!plugin) return { inputs, claimed };
+  const byDir = new Map<string, Record<string, string>>();
+  for (const f of files) {
+    if (!isTerraformFileName(basename(f.path))) continue;
+    const slash = f.path.lastIndexOf("/");
+    const dir = slash === -1 ? "" : f.path.slice(0, slash);
+    const name = slash === -1 ? f.path : f.path.slice(slash + 1);
+    const bundle = byDir.get(dir) ?? {};
+    bundle[name] = f.content;
+    byDir.set(dir, bundle);
+    claimed.add(f.path);
+  }
+  const childModules = baseDir === undefined ? new Set<string>() : calledAsLocalModule(byDir);
+  for (const [dir, bundle] of byDir) {
+    if (childModules.has(dir)) continue;
+    // `content` is the whole root module, every `.tf` in filename order with a
+    // `# file:` line comment (legal HCL) marking each boundary, so a lexicon's
+    // `auditEntities(content)` sees the module Terraform itself would load,
+    // not one arbitrary file of it. `files` keeps the per-file split, and
+    // `dir` is where the local modules it calls are read from.
+    const content = Object.keys(bundle)
+      .sort()
+      .map((name) => `# file: ${name}\n${bundle[name]}`)
+      .join("\n");
+    inputs.push({
+      path: dir === "" ? "." : dir,
+      content,
+      lexicon: "terraform",
+      files: bundle,
+      ...(baseDir === undefined ? {} : { dir: resolve(baseDir, dir), baseDir }),
+    });
+  }
+  return { inputs, claimed };
+}
+
+/** Where a set of classified files came from, when they came from a local walk (#2217). */
+export interface ClassifyOptions {
+  /**
+   * Absolute path of the directory that was walked. Travels onto the inputs
+   * whose `path` names a directory, so a lexicon's `auditEntities` can read
+   * the files that directory references (terraform's local module calls).
+   * Omit for an in-memory or fetched file set: there is no directory to read.
+   */
+  baseDir?: string;
+}
+
 /**
  * Classify an in-memory set of repo files into per-lexicon audit inputs. Pure
  * (no fs, no network) so the local walk and the remote tree-fetch share exactly
  * one detection path. Each file maps to at most one lexicon: CI by path,
- * Dockerfiles by name, Helm charts as a bundle, everything else by the
- * precedence-ordered content detectors (delegating to each plugin's
- * `detectTemplate`). Lexicons whose plugin isn't provided are skipped.
+ * Dockerfiles by name, Helm charts and Terraform root modules as directory
+ * bundles, everything else by the precedence-ordered content detectors
+ * (delegating to each plugin's `detectTemplate`). Lexicons whose plugin isn't
+ * provided are skipped.
  */
-export function classifyFiles(files: RepoFile[], plugins: DetectPlugin[]): AuditInput[] {
+export function classifyFiles(files: RepoFile[], plugins: DetectPlugin[], opts: ClassifyOptions = {}): AuditInput[] {
   const byName = new Map(plugins.map((p) => [p.name, p]));
+  const baseDir = opts.baseDir === undefined ? undefined : resolve(opts.baseDir);
 
   // Helm claims whole chart directories first; chart-internal files are excluded
   // from the loose-file pass so templates aren't double-audited.
   const helm = classifyHelm(files, byName.get("helm"));
   const underChart = (p: string): boolean => helm.prefixes.some((pre) => (pre === "" ? true : p.startsWith(pre)));
 
-  const inputs: AuditInput[] = [...helm.inputs];
+  const terraform = classifyTerraform(files, byName.get("terraform"), baseDir);
+
+  const inputs: AuditInput[] = [...helm.inputs, ...terraform.inputs];
   for (const { path, content } of files) {
     if (underChart(path)) continue;
+    if (terraform.claimed.has(path)) continue;
     const name = basename(path);
 
     const ci = ciLexiconForPath(path);
@@ -420,20 +591,33 @@ export function classifyFiles(files: RepoFile[], plugins: DetectPlugin[]): Audit
  * lexicon whose plugin isn't provided, so a caller can scope discovery.
  */
 export function discoverByDetection(root: string, plugins: DetectPlugin[]): AuditInput[] {
-  return classifyFiles(collectCandidates(root), plugins);
+  return classifyFiles(collectCandidates(root), plugins, { baseDir: root });
 }
 
 /** The walk half of `discoverByDetection`: candidate files read into memory, paths relative to the root. */
 export function collectCandidates(root: string): RepoFile[] {
   const all: string[] = [];
   walkFiles(root, all);
+  // TF023 reads paths, not content: a `.tfstate` can be tens of megabytes of
+  // machine-generated JSON, and the finding is that it is in the repository at
+  // all. The root `.gitignore` is what separates "committed" from "merely on
+  // disk" here — a Terraform working tree almost always has an ignored
+  // `.terraform/` in it, and reporting that would make TF023 fire on every
+  // local audit. A fetched repository has no such ambiguity (its file list is
+  // the tracked files) and is not filtered.
+  const gitignore = readSafe(join(root, ".gitignore")) ?? "";
   const files: RepoFile[] = [];
   for (const full of all) {
     const path = relative(root, full);
-    // Terraform is never audited; the path alone is enough to say so (#1623).
-    // Kept out of `isCandidatePath` so remote fetches never pull HCL.
-    if (/\.tf$/i.test(path)) {
-      files.push({ path, content: "" });
+    if (isTerraformStatePath(path)) {
+      if (!gitignoreCoversTerraformState(gitignore, path)) files.push({ path, content: "" });
+      continue;
+    }
+    // `.tf` is read locally so `classifyTerraform` can bundle real content.
+    // It stays out of `isCandidatePath` so remote fetches still never pull HCL.
+    if (isTerraformFileName(basename(path))) {
+      const content = readSafe(full);
+      if (content !== undefined) files.push({ path, content });
       continue;
     }
     if (!isCandidatePath(path)) continue;

package/src/audit/lineage.ts

@@ -0,0 +1,100 @@
+/**
+ * Prior art for these audit rules: the open-source tools whose checks cover the
+ * same condition, credited per rule. See packages/core/src/audit/prior-art.ts for
+ * the registry, the relation vocabulary, and why this is credit rather than
+ * authority. Kept by hand; the prior-art sweep (scripts/prior-art-sweep.ts) reports
+ * when a credited tool's index no longer lists a rule cited here.
+ */
+import type { Lineage } from "./prior-art";
+
+export const coreAuditLineage: Record<string, Lineage[]> = {
+  AGT002: [
+    { tool: "agent-audit", rule: "auth-bypass/env-secret-in-config", url: "https://raw.githubusercontent.com/piiiico/agent-audit/main/README.md", relation: "equivalent" },
+    { tool: "mcp-audit", rule: "Secrets Detection", url: "https://raw.githubusercontent.com/apisec-inc/mcp-audit/main/README.md", relation: "overlaps" },
+    { tool: "agent-scan", rule: "W008", url: "https://raw.githubusercontent.com/invariantlabs-ai/mcp-scan/main/docs/issue-codes.md", relation: "overlaps" },
+  ],
+  COR020: [
+    { tool: "cfn-lint", rule: "E3004", url: "https://github.com/aws-cloudformation/cfn-lint/blob/main/docs/rules.md#E3004", relation: "equivalent" },
+  ],
+  EXT001: [
+    { tool: "cfn-lint", url: "https://github.com/aws-cloudformation/cfn-lint/blob/main/docs/cfn-schema-specification.md#extending-the-schemas-with-new-keywords", relation: "equivalent" },
+    { tool: "cfn-lint", rule: "E3014", url: "https://github.com/aws-cloudformation/cfn-lint/blob/main/docs/rules.md#E3014", relation: "equivalent" },
+    { tool: "cfn-lint", rule: "E3021", url: "https://github.com/aws-cloudformation/cfn-lint/blob/main/docs/rules.md#E3021", relation: "equivalent" },
+  ],
+  NGX001: [
+    { tool: "gixy-ng", rule: "weak_ssl_tls", url: "https://gixy.getpagespeed.com/plugins/weak_ssl_tls/", relation: "overlaps" },
+  ],
+  NGX002: [
+    { tool: "gixy-ng", rule: "weak_ssl_tls", url: "https://gixy.getpagespeed.com/plugins/weak_ssl_tls/", relation: "overlaps" },
+  ],
+  NGX004: [
+    { tool: "gixy", rule: "alias_traversal", url: "https://github.com/yandex/gixy", relation: "equivalent" },
+    { tool: "gixy-ng", rule: "alias_traversal", url: "https://gixy.getpagespeed.com/plugins/aliastraversal/", relation: "equivalent" },
+  ],
+  NGX005: [
+    { tool: "gixy-ng", rule: "status_page_exposed", url: "https://gixy.getpagespeed.com/checks/status-page-exposed/", relation: "overlaps" },
+  ],
+  NGX006: [
+    { tool: "gixy-ng", rule: "version_disclosure", url: "https://gixy.getpagespeed.com/plugins/version_disclosure/", relation: "equivalent" },
+  ],
+  SEC001: [
+    { tool: "gitleaks", rule: "aws-access-token", url: "https://github.com/gitleaks/gitleaks/blob/master/config/gitleaks.toml", relation: "equivalent" },
+    { tool: "trufflehog", rule: "aws", url: "https://github.com/trufflesecurity/trufflehog/blob/main/pkg/detectors/aws/access_keys/accesskey.go", relation: "overlaps" },
+    { tool: "detect-secrets", rule: "AWSKeyDetector", url: "https://github.com/Yelp/detect-secrets/blob/master/detect_secrets/plugins/aws.py", relation: "equivalent" },
+  ],
+  SEC002: [
+    { tool: "gitleaks", rule: "generic-api-key", url: "https://github.com/gitleaks/gitleaks/blob/master/config/gitleaks.toml", relation: "overlaps" },
+    { tool: "trufflehog", rule: "aws", url: "https://github.com/trufflesecurity/trufflehog/blob/main/pkg/detectors/aws/access_keys/accesskey.go", relation: "overlaps" },
+    { tool: "detect-secrets", rule: "AWSKeyDetector", url: "https://github.com/Yelp/detect-secrets/blob/master/detect_secrets/plugins/aws.py", relation: "overlaps" },
+  ],
+  SEC003: [
+    { tool: "gitleaks", rule: "github-pat", url: "https://github.com/gitleaks/gitleaks/blob/master/config/gitleaks.toml", relation: "overlaps" },
+    { tool: "trufflehog", rule: "github", url: "https://github.com/trufflesecurity/trufflehog/blob/main/pkg/detectors/github/v2/github.go", relation: "equivalent" },
+    { tool: "detect-secrets", rule: "GitHubTokenDetector", url: "https://github.com/Yelp/detect-secrets/blob/master/detect_secrets/plugins/github_token.py", relation: "overlaps" },
+  ],
+  SEC004: [
+    { tool: "gitleaks", rule: "slack-bot-token", url: "https://github.com/gitleaks/gitleaks/blob/master/config/gitleaks.toml", relation: "overlaps" },
+    { tool: "trufflehog", rule: "slack", url: "https://github.com/trufflesecurity/trufflehog/blob/main/pkg/detectors/slack/slack.go", relation: "overlaps" },
+    { tool: "detect-secrets", rule: "SlackDetector", url: "https://github.com/Yelp/detect-secrets/blob/master/detect_secrets/plugins/slack.py", relation: "overlaps" },
+  ],
+  SEC005: [
+    { tool: "gitleaks", rule: "gcp-api-key", url: "https://github.com/gitleaks/gitleaks/blob/master/config/gitleaks.toml", relation: "equivalent" },
+    { tool: "trufflehog", rule: "googlegemini", url: "https://github.com/trufflesecurity/trufflehog/blob/main/pkg/detectors/googlegemini/googlegemini.go", relation: "overlaps" },
+  ],
+  SEC006: [
+    { tool: "gitleaks", rule: "stripe-access-token", url: "https://github.com/gitleaks/gitleaks/blob/master/config/gitleaks.toml", relation: "overlaps" },
+    { tool: "trufflehog", rule: "stripe", url: "https://github.com/trufflesecurity/trufflehog/blob/main/pkg/detectors/stripe/stripe.go", relation: "overlaps" },
+    { tool: "detect-secrets", rule: "StripeDetector", url: "https://github.com/Yelp/detect-secrets/blob/master/detect_secrets/plugins/stripe.py", relation: "overlaps" },
+  ],
+  SEC007: [
+    { tool: "gitleaks", rule: "private-key", url: "https://github.com/gitleaks/gitleaks/blob/master/config/gitleaks.toml", relation: "equivalent" },
+    { tool: "trufflehog", rule: "privatekey", url: "https://github.com/trufflesecurity/trufflehog/blob/main/pkg/detectors/privatekey/privatekey.go", relation: "equivalent" },
+    { tool: "detect-secrets", rule: "PrivateKeyDetector", url: "https://github.com/Yelp/detect-secrets/blob/master/detect_secrets/plugins/private_key.py", relation: "equivalent" },
+  ],
+  SEC008: [
+    { tool: "gitleaks", rule: "curl-auth-header", url: "https://github.com/gitleaks/gitleaks/blob/master/config/gitleaks.toml", relation: "overlaps" },
+  ],
+  SEC009: [
+    { tool: "detect-secrets", rule: "BasicAuthDetector", url: "https://github.com/Yelp/detect-secrets/blob/master/detect_secrets/plugins/basic_auth.py", relation: "equivalent" },
+    { tool: "trufflehog", rule: "uri", url: "https://github.com/trufflesecurity/trufflehog/blob/main/pkg/detectors/uri/uri.go", relation: "overlaps" },
+    { tool: "gitleaks", rule: "curl-auth-user", url: "https://github.com/gitleaks/gitleaks/blob/master/config/gitleaks.toml", relation: "overlaps" },
+  ],
+  SEC010: [
+    { tool: "detect-secrets", rule: "Base64HighEntropyString", url: "https://github.com/Yelp/detect-secrets/blob/master/detect_secrets/plugins/high_entropy_strings.py", relation: "overlaps" },
+    { tool: "detect-secrets", rule: "HexHighEntropyString", url: "https://github.com/Yelp/detect-secrets/blob/master/detect_secrets/plugins/high_entropy_strings.py", relation: "overlaps" },
+    { tool: "gitleaks", rule: "generic-api-key", url: "https://github.com/gitleaks/gitleaks/blob/master/config/gitleaks.toml", relation: "overlaps" },
+  ],
+  // TF023 is the one TF id core owns (./terraform-state.ts); the rest of the
+  // family credits its prior art from lexicons/terraform/src/lint/audit-lineage.ts.
+  // No linter or scanner in #2107's survey checks for committed state, but the
+  // style guide's .gitignore section names the exact files, so the document is
+  // both the authority and the first written statement of the rule.
+  TF023: [
+    {
+      tool: "hashicorp-style-guide",
+      rule: ".gitignore: do not commit terraform.tfstate, terraform.tfstate.* backups, or the .terraform directory",
+      url: "https://developer.hashicorp.com/terraform/language/style#gitignore",
+      relation: "equivalent",
+    },
+  ],
+};

package/src/audit/prior-art.ts

@@ -0,0 +1,153 @@
+/**
+ * Prior art for chant's audit rules.
+ *
+ * Most of what `chant audit` checks has been checked before by a dedicated
+ * open-source tool: zizmor and poutine for GitHub Actions, hadolint for
+ * Dockerfiles, cfn-lint and cfn_nag for CloudFormation, kube-linter and
+ * kube-score for Kubernetes manifests, gitleaks for secrets, and so on. chant's
+ * rules were written independently against the emitted output, but the ideas
+ * are shared, and the people who wrote them down first deserve the credit.
+ *
+ * A rule declares its lineage as `Lineage[]` on its `RuleMeta` entry: which
+ * tool, which upstream rule, where it is documented, and how the two relate.
+ * `PRIOR_ART` is the registry those entries key into, so a tool is named,
+ * linked and licensed once. The audit rules reference renders both, the
+ * markdown and HTML reports credit the tool beside the finding, and the SARIF
+ * and JSON outputs carry the entries verbatim for consumers.
+ *
+ * Lineage is credit, not authority. `authority` (./catalog.ts) is a standard
+ * or vendor document that says a finding matters; lineage is a tool that
+ * checks the same condition. The two are independent: a rule may have either,
+ * both, or neither, and lineage never changes a rule's category or tier.
+ */
+
+/** How a chant rule relates to the upstream check it credits. */
+export type LineageRelation =
+  /** Same condition, same scope. */
+  | "equivalent"
+  /** The core condition is shared; one side is narrower or broader, or a different dialect of the same control. */
+  | "overlaps"
+  /** chant checks a strict superset of the upstream check. */
+  | "extends";
+
+/** One credit: an upstream tool's rule that checks what this chant rule checks. */
+export interface Lineage {
+  /** A key of {@link PRIOR_ART}. */
+  tool: PriorArtTool;
+  /** The upstream rule id or check name, in the tool's own vocabulary (e.g. `template-injection`, `DL3007`, `CKV_AWS_18`). Omitted when the tool has no per-rule ids. */
+  rule?: string;
+  /** Where the upstream rule is documented. */
+  url: string;
+  relation: LineageRelation;
+}
+
+/** A tool (or, for a few families, a vendor validator) that chant's rules credit. */
+export interface PriorArtEntry {
+  name: string;
+  url: string;
+  /** SPDX identifier where confirmed, else "unverified" or "n/a" for documentation. */
+  license: string;
+  /** What kind of thing this is, so the rendered credit is honest about it. */
+  kind: "scanner" | "vendor-validator" | "specification";
+}
+
+/**
+ * The registry of prior art. Keys are the slugs `Lineage.tool` uses. Populated
+ * from the per-family research recorded in the PR that introduced lineage; the
+ * prior-art sweep (scripts/prior-art-sweep.ts) reads the same table.
+ */
+export const PRIOR_ART = {
+  "checkov": { name: "Checkov", url: "https://www.checkov.io/", license: "Apache-2.0", kind: "scanner" },
+  "kics": { name: "KICS", url: "https://docs.kics.io/", license: "Apache-2.0", kind: "scanner" },
+  "zizmor": { name: "zizmor", url: "https://docs.zizmor.sh/", license: "MIT", kind: "scanner" },
+  "cfn-nag": { name: "cfn_nag", url: "https://github.com/stelligent/cfn_nag", license: "MIT", kind: "scanner" },
+  "gitlab-docs": { name: "GitLab CI/CD YAML reference", url: "https://docs.gitlab.com/ci/yaml/", license: "CC-BY-SA-4.0", kind: "specification" },
+  "guard-rules-registry": { name: "AWS Guard Rules Registry", url: "https://github.com/aws-cloudformation/aws-guard-rules-registry", license: "Apache-2.0", kind: "scanner" },
+  "polaris": { name: "Fairwinds Polaris", url: "https://polaris.docs.fairwinds.com/", license: "Apache-2.0", kind: "scanner" },
+  "kube-linter": { name: "KubeLinter", url: "https://github.com/stackrox/kube-linter", license: "Apache-2.0", kind: "scanner" },
+  "kube-score": { name: "kube-score", url: "https://github.com/zegl/kube-score", license: "MIT", kind: "scanner" },
+  "psrule-azure": { name: "PSRule for Azure", url: "https://azure.github.io/PSRule.Rules.Azure/", license: "MIT", kind: "scanner" },
+  "gcp-policy-library": { name: "Google Cloud Policy Library", url: "https://github.com/GoogleCloudPlatform/policy-library", license: "Apache-2.0", kind: "scanner" },
+  "poutine": { name: "poutine", url: "https://boostsecurityio.github.io/poutine/", license: "Apache-2.0", kind: "scanner" },
+  "scorecard": { name: "OpenSSF Scorecard", url: "https://github.com/ossf/scorecard", license: "Apache-2.0", kind: "scanner" },
+  "cfn-lint": { name: "cfn-lint", url: "https://github.com/aws-cloudformation/cfn-lint", license: "MIT-0", kind: "scanner" },
+  "controlplane-docs": { name: "Control Plane reference documentation", url: "https://docs.controlplane.com", license: "n/a", kind: "specification" },
+  "gitleaks": { name: "gitleaks", url: "https://github.com/gitleaks/gitleaks", license: "MIT", kind: "scanner" },
+  "octoscan": { name: "octoscan", url: "https://github.com/synacktiv/octoscan", license: "GPL-3.0", kind: "scanner" },
+  "detect-secrets": { name: "detect-secrets", url: "https://github.com/Yelp/detect-secrets", license: "Apache-2.0", kind: "scanner" },
+  "actionlint": { name: "actionlint", url: "https://github.com/rhysd/actionlint", license: "MIT", kind: "scanner" },
+  "trufflehog": { name: "TruffleHog", url: "https://github.com/trufflesecurity/trufflehog", license: "AGPL-3.0", kind: "scanner" },
+  "gixy-ng": { name: "gixy-ng (maintained Gixy fork)", url: "https://github.com/dvershinin/gixy", license: "MPL-2.0", kind: "scanner" },
+  "kubesec": { name: "kubesec", url: "https://kubesec.io/", license: "Apache-2.0", kind: "scanner" },
+  "datree": { name: "Datree", url: "https://hub.datree.io/built-in-rules", license: "Apache-2.0", kind: "scanner" },
+  "helm-lint": { name: "helm lint", url: "https://helm.sh/docs/helm/helm_lint/", license: "Apache-2.0", kind: "vendor-validator" },
+  "cedar-validator": { name: "Cedar policy validator", url: "https://docs.cedarpolicy.com/policies/validation.html", license: "Apache-2.0", kind: "vendor-validator" },
+  "flux-docs": { name: "Flux Kustomization API reference", url: "https://fluxcd.io/flux/components/kustomize/kustomizations/", license: "n/a", kind: "specification" },
+  "hadolint": { name: "hadolint", url: "https://github.com/hadolint/hadolint", license: "GPL-3.0", kind: "scanner" },
+  "agent-audit": { name: "agent-audit", url: "https://github.com/piiiico/agent-audit", license: "MIT", kind: "scanner" },
+  "arm-ttk": { name: "ARM Template Toolkit (arm-ttk)", url: "https://github.com/Azure/arm-ttk", license: "MIT", kind: "scanner" },
+  "bicep-linter": { name: "Bicep linter", url: "https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/linter", license: "MIT", kind: "scanner" },
+  "cedar-cli": { name: "Cedar CLI", url: "https://github.com/cedar-policy/cedar/tree/main/cedar-policy-cli", license: "Apache-2.0", kind: "vendor-validator" },
+  "dockle": { name: "Dockle", url: "https://github.com/goodwithtech/dockle", license: "Apache-2.0", kind: "scanner" },
+  "mcp-audit": { name: "mcp-audit (APIsec)", url: "https://github.com/apisec-inc/mcp-audit", license: "MIT", kind: "scanner" },
+  "render-docs": { name: "Render Blueprint YAML reference", url: "https://render.com/docs/blueprint-spec", license: "n/a", kind: "specification" },
+  "agent-scan": { name: "Snyk Agent Scan (formerly mcp-scan)", url: "https://github.com/invariantlabs-ai/mcp-scan", license: "Apache-2.0", kind: "scanner" },
+  "cedar-docs": { name: "Cedar policy language reference", url: "https://docs.cedarpolicy.com/policies/json-format.html", license: "n/a", kind: "specification" },
+  "cedar-policy-crate": { name: "cedar-policy crate (PolicySet loader)", url: "https://docs.rs/cedar-policy/latest/cedar_policy/", license: "Apache-2.0", kind: "vendor-validator" },
+  "chart-testing": { name: "chart-testing (ct)", url: "https://github.com/helm/chart-testing", license: "Apache-2.0", kind: "vendor-validator" },
+  "fly-docs": { name: "Fly Machines API reference", url: "https://fly.io/docs/machines/api/machines-resource/", license: "n/a", kind: "specification" },
+  "gixy": { name: "Gixy", url: "https://github.com/yandex/gixy", license: "MPL-2.0", kind: "scanner" },
+  "kube-bench": { name: "kube-bench", url: "https://github.com/aquasecurity/kube-bench", license: "Apache-2.0", kind: "scanner" },
+  "pluto": { name: "Pluto", url: "https://github.com/FairwindsOps/pluto", license: "Apache-2.0", kind: "scanner" },
+  "choudoufu": { name: "choudoufu", url: "https://github.com/INTENTIUS/choudoufu", license: "MPL-2.0", kind: "scanner" },
+  // Terraform lint family (#2107). Registry entries recorded in
+  // lexicons/terraform/src/lint/audit-lineage.ts's header comment; added here
+  // the first time a shipped rule cites them (#2109).
+  "tflint-ruleset-terraform": { name: "tflint-ruleset-terraform", url: "https://github.com/terraform-linters/tflint-ruleset-terraform", license: "MPL-2.0", kind: "scanner" },
+  "terraform-sentinel-policies": { name: "HashiCorp reference Sentinel policies", url: "https://github.com/hashicorp/terraform-sentinel-policies", license: "MPL-2.0", kind: "specification" },
+  "hashicorp-style-guide": { name: "HashiCorp Terraform style guide", url: "https://developer.hashicorp.com/terraform/language/style", license: "n/a", kind: "specification" },
+  "aws-terraform-prescriptive-guidance": { name: "AWS prescriptive guidance for Terraform", url: "https://docs.aws.amazon.com/prescriptive-guidance/latest/terraform-aws-provider-best-practices/", license: "n/a", kind: "specification" },
+  // A multi-page series; a credit cites the specific page and fragment, not
+  // this landing URL. First cited by TF014 and TF015 (#2112).
+  "gcp-terraform-best-practices": { name: "Google Cloud Terraform best-practices series", url: "https://docs.cloud.google.com/docs/terraform/best-practices/general-style-structure", license: "n/a", kind: "specification" },
+  "tflint-ruleset-redeploy": { name: "tflint-ruleset-redeploy", url: "https://github.com/RedeployAB/tflint-ruleset-redeploy", license: "0BSD", kind: "scanner" },
+  "tflint-ruleset-avm": { name: "tflint-ruleset-avm (Azure Verified Modules)", url: "https://github.com/Azure/tflint-ruleset-avm", license: "MIT", kind: "scanner" },
+  // tfsec is frozen rather than archived, and its docs site 404s above v0.61.x,
+  // so its credits cite pinned repository paths (a tag or `master`), never the
+  // docs site. The three `general/secrets` checks chant credits live only here:
+  // trivy dropped them when it absorbed tfsec.
+  "tfsec": { name: "tfsec", url: "https://github.com/aquasecurity/tfsec", license: "MIT", kind: "scanner" },
+  // Semgrep's engine is LGPL-2.1 but its rules are not: they ship under the
+  // proprietary Semgrep Rules License v1.0, which forbids redistribution. So
+  // this entry carries no SPDX id, and no semgrep rule text is ever copied into
+  // this repository — a credit by name and link is the whole of it (#2107).
+  "semgrep": { name: "Semgrep Registry rules", url: "https://github.com/semgrep/semgrep-rules", license: "Semgrep Rules License v1.0 (proprietary, not an SPDX id)", kind: "scanner" },
+} as const satisfies Record<string, PriorArtEntry>;
+
+export type PriorArtTool = keyof typeof PRIOR_ART;
+
+/**
+ * Attach lineage to a catalog in place. A lexicon keeps its lineage in a
+ * sibling `audit-lineage.ts` (one `Record<ruleId, Lineage[]>`) and calls this
+ * once at the bottom of its `audit-catalog.ts`, so the prose metadata and the
+ * credits stay next to each other but the credits can be regenerated by the
+ * prior-art sweep without touching the rule text. Throws at module load if the
+ * lineage names a rule the catalog does not have: a stale id is a bug, not a
+ * silent no-op.
+ */
+export function applyLineage<T extends { id: string; lineage?: Lineage[] }>(
+  catalog: Record<string, T>,
+  lineage: Record<string, Lineage[]>,
+): void {
+  for (const [id, entries] of Object.entries(lineage)) {
+    const rule = catalog[id];
+    if (!rule) throw new Error(`audit lineage names ${id}, which this catalog does not define`);
+    if (entries.length > 0) rule.lineage = entries;
+  }
+}
+
+/** Render one lineage entry as "tool rule (relation)" for prose contexts. */
+export function lineageLabel(l: Lineage): string {
+  const tool = (PRIOR_ART as Record<string, PriorArtEntry>)[l.tool]?.name ?? l.tool;
+  return l.rule ? `${tool} ${l.rule}` : tool;
+}