@intentius/chant 0.7.0 → 0.8.1

package/src/audit/fetch.ts

@@ -1,21 +1,21 @@
 /**
- * Remote fetch — pull a repo's CI files from a git host so the auditor can run
- * on a URL, not just a local path. This is the ONLY audit module that touches
- * the network; the core stays pure.
+ * Remote fetch — pull a repo's candidate files (all lexicons) from a git host so
+ * the auditor can run on a URL, not just a local path. This is the ONLY audit
+ * module that touches the network; the core stays pure.
  *
  * SSRF posture: only an allowlisted set of hosts is accepted; request URLs are
  * built from the parsed owner/repo (never a user-controlled host); redirects
  * are refused; and file count / size / total bytes / time are all capped.
  */
 
-import type { AuditInput, AuditLexicon } from "./core";
+import type { AuditLexicon } from "./core";
 
 export interface FetchOptions {
   /** Branch/tag/sha; defaults to the repo's default branch. */
   ref?: string;
   /** Server-side token (lifts rate limits). Never surfaced to callers. */
   token?: string;
-  /** Max number of CI files to fetch (default 50). */
+  /** Max number of files to fetch (default 50). */
   maxFiles?: number;
   /** Max bytes for a single file; larger files are skipped (default 256 KiB). */
   maxBytesPerFile?: number;
@@ -80,15 +80,16 @@ export function parseRepoUrl(url: string): ParsedRepo {
   return { host, owner: parts[0], repo: parts[1].replace(/\.git$/, "") };
 }
 
-function authHeaders(kind: HostKind, token?: string): Record<string, string> {
-  if (!token) return {};
-  if (kind === "github") return { Authorization: `Bearer ${token}` };
-  if (kind === "forgejo") return { Authorization: `token ${token}` };
-  return { "PRIVATE-TOKEN": token };
-}
+/** GitHub (and good manners) require a User-Agent — workerd's fetch sends none,
+ * so a missing UA 403s every request. Always set one, with or without a token. */
+const USER_AGENT = "chant-audit (+https://github.com/intentius/chant)";
 
-function isYaml(name: string): boolean {
-  return name.endsWith(".yml") || name.endsWith(".yaml");
+function authHeaders(kind: HostKind, token?: string): Record<string, string> {
+  const base = { "User-Agent": USER_AGENT };
+  if (!token) return base;
+  if (kind === "github") return { ...base, Authorization: `Bearer ${token}` };
+  if (kind === "forgejo") return { ...base, Authorization: `token ${token}` };
+  return { ...base, "PRIVATE-TOKEN": token };
 }
 
 function timeoutSignal(ms: number): AbortSignal | undefined {
@@ -107,7 +108,150 @@ interface ContentsEntry {
   encoding?: string;
 }
 
-export async function fetchCiFiles(url: string, opts: FetchOptions = {}): Promise<AuditInput[]> {
+// ── Whole-repo fetch (all lexicons, not just CI) ─────────────────────────────
+// Mirrors the local walk: list the repo tree, keep candidate paths, fetch their
+// contents (capped), and hand the raw {path, content} set to the shared
+// classifier in discover.ts. SSRF posture is unchanged — allowlisted host,
+// URLs built from parsed owner/repo, redirects refused, counts/bytes capped.
+
+/** Module-level JSON GET that refuses redirects (reused by the tree-walk). */
+async function getJsonAt(
+  url: string,
+  headers: Record<string, string>,
+  doFetch: typeof fetch,
+  timeoutMs: number,
+): Promise<{ status: number; body: unknown }> {
+  let res: Response;
+  try {
+    res = await doFetch(url, { headers, redirect: "manual", signal: timeoutSignal(timeoutMs) });
+  } catch (err) {
+    throw new FetchError(`Request failed: ${err instanceof Error ? err.message : String(err)}`);
+  }
+  if (res.status >= 300 && res.status < 400) throw new FetchError(`Refusing to follow redirect from ${url}`);
+  if (res.status === 404) return { status: 404, body: null };
+  if (!res.ok) throw new FetchError(`${url} returned ${res.status}`);
+  return { status: res.status, body: await res.json() };
+}
+
+function projectId(owner: string, repo: string): string {
+  return encodeURIComponent(`${owner}/${repo}`);
+}
+
+/** The repo's default branch, so the tree request has a concrete ref. */
+async function defaultBranch(host: HostConfig, owner: string, repo: string, doFetch: typeof fetch, headers: Record<string, string>, ms: number): Promise<string> {
+  const url =
+    host.kind === "gitlab"
+      ? `${host.api}/projects/${projectId(owner, repo)}`
+      : `${host.api}/repos/${owner}/${repo}`;
+  const { body } = await getJsonAt(url, headers, doFetch, ms);
+  const branch = (body as { default_branch?: string } | null)?.default_branch;
+  return branch && typeof branch === "string" ? branch : "HEAD";
+}
+
+interface TreeEntry {
+  path: string;
+  type: string;
+  size?: number;
+}
+
+/** List every blob path in the repo (recursive), with size where the host reports it. */
+async function listTree(host: HostConfig, owner: string, repo: string, ref: string, doFetch: typeof fetch, headers: Record<string, string>, ms: number): Promise<TreeEntry[]> {
+  if (host.kind === "gitlab") {
+    const out: TreeEntry[] = [];
+    const MAX_PAGES = 20; // 20 * 100 = 2000 entries — bounded; candidate filter + caps trim further
+    for (let page = 1; page <= MAX_PAGES; page++) {
+      const url = `${host.api}/projects/${projectId(owner, repo)}/repository/tree?recursive=true&per_page=100&page=${page}&ref=${encodeURIComponent(ref)}`;
+      const { body } = await getJsonAt(url, headers, doFetch, ms);
+      if (!Array.isArray(body) || body.length === 0) break;
+      for (const e of body as Array<{ path: string; type: string }>) {
+        if (e.type === "blob") out.push({ path: e.path, type: "blob" });
+      }
+      if (body.length < 100) break;
+    }
+    return out;
+  }
+  // GitHub / Forgejo (Gitea) share the git/trees recursive API.
+  const url = `${host.api}/repos/${owner}/${repo}/git/trees/${encodeURIComponent(ref)}?recursive=1`;
+  const { body } = await getJsonAt(url, headers, doFetch, ms);
+  const tree = (body as { tree?: TreeEntry[] } | null)?.tree;
+  if (!Array.isArray(tree)) return [];
+  return tree.filter((e) => e.type === "blob").map((e) => ({ path: e.path, type: "blob", size: e.size }));
+}
+
+/**
+ * Resilient GET → text. Returns undefined on any error or non-ok status, so one
+ * file's failure (a bad path, a 403 secondary rate-limit, a timeout) never
+ * aborts the whole walk. `redirect: "manual"` keeps the SSRF posture — a 3xx is
+ * skipped, never followed.
+ */
+async function fetchText(url: string, headers: Record<string, string>, doFetch: typeof fetch, ms: number): Promise<string | undefined> {
+  let res: Response;
+  try {
+    res = await doFetch(url, { headers, redirect: "manual", signal: timeoutSignal(ms) });
+  } catch {
+    return undefined;
+  }
+  if (!res.ok) return undefined;
+  try {
+    return await res.text();
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Fetch one file's content. GitHub reads from the raw CDN first — a burst of
+ * contents-API calls trips GitHub's *secondary* rate limit on large repos
+ * (dozens of files), whereas raw.githubusercontent.com isn't subject to it and
+ * needs no auth for public repos. The contents API is the fallback for private
+ * repos (raw 404s there without auth). GitLab uses its raw endpoint; Forgejo
+ * uses the contents API.
+ */
+async function fetchFileContent(host: HostConfig, owner: string, repo: string, path: string, ref: string, doFetch: typeof fetch, headers: Record<string, string>, ms: number): Promise<string | undefined> {
+  // Encode each segment (keep the slashes) — paths can contain spaces and other
+  // characters that make an unencoded URL malformed and 403 (e.g. GitHub's
+  // changelog fragments like ".changes/v1.16/NEW FEATURES-….yaml").
+  const encodedPath = path.split("/").map(encodeURIComponent).join("/");
+
+  if (host.kind === "gitlab") {
+    const url = `${host.api}/projects/${projectId(owner, repo)}/repository/files/${encodeURIComponent(path)}/raw?ref=${encodeURIComponent(ref)}`;
+    return fetchText(url, headers, doFetch, ms);
+  }
+
+  if (host.kind === "github") {
+    // No token sent cross-host to the CDN; public repos need none.
+    const rawUrl = `https://raw.githubusercontent.com/${owner}/${repo}/${encodeURIComponent(ref)}/${encodedPath}`;
+    const raw = await fetchText(rawUrl, { "User-Agent": USER_AGENT }, doFetch, ms);
+    if (raw !== undefined) return raw;
+    // Private repo (raw 404s without auth) — fall through to the contents API.
+  }
+
+  // Contents API: base64 JSON. Forgejo always; GitHub private-repo fallback.
+  const url = `${host.api}/repos/${owner}/${repo}/contents/${encodedPath}?ref=${encodeURIComponent(ref)}`;
+  let res: Response;
+  try {
+    res = await doFetch(url, { headers, redirect: "manual", signal: timeoutSignal(ms) });
+  } catch {
+    return undefined;
+  }
+  if (!res.ok) return undefined;
+  let file: ContentsEntry | null;
+  try {
+    file = (await res.json()) as ContentsEntry | null;
+  } catch {
+    return undefined;
+  }
+  if (!file?.content) return undefined;
+  return Buffer.from(file.content, (file.encoding as BufferEncoding) ?? "base64").toString("utf-8");
+}
+
+/**
+ * Fetch every candidate file in a repo (all lexicons), so a URL audit covers the
+ * same ground as a local one. Returns raw {path, content}; classification (which
+ * needs the lexicon plugins) is the caller's job via `classifyFiles`.
+ */
+export async function fetchRepoFiles(url: string, opts: FetchOptions = {}): Promise<Array<{ path: string; content: string }>> {
+  const { isCandidatePath } = await import("./discover");
   const { host, owner, repo } = parseRepoUrl(url);
   const doFetch = opts.fetchImpl ?? fetch;
   const cfg = {
@@ -117,58 +261,24 @@ export async function fetchCiFiles(url: string, opts: FetchOptions = {}): Promis
     timeoutMs: opts.timeoutMs ?? DEFAULTS.timeoutMs,
   };
   const headers = authHeaders(host.kind, opts.token);
+  const ref = opts.ref ?? (await defaultBranch(host, owner, repo, doFetch, headers, cfg.timeoutMs));
 
-  async function getJson(apiUrl: string): Promise<{ status: number; body: unknown }> {
-    let res: Response;
-    try {
-      res = await doFetch(apiUrl, { headers, redirect: "error", signal: timeoutSignal(cfg.timeoutMs) });
-    } catch (err) {
-      throw new FetchError(`Request failed: ${err instanceof Error ? err.message : String(err)}`);
-    }
-    if (res.status >= 300 && res.status < 400) {
-      throw new FetchError(`Refusing to follow redirect from ${apiUrl}`);
-    }
-    if (res.status === 404) return { status: 404, body: null };
-    if (!res.ok) throw new FetchError(`${apiUrl} returned ${res.status}`);
-    return { status: res.status, body: await res.json() };
-  }
-
-  if (host.kind === "gitlab") {
-    return fetchGitlab(host, owner, repo, opts.ref, cfg, doFetch, headers);
-  }
-
-  // GitHub / Forgejo share the Gitea-style contents API.
-  const dirs = host.kind === "forgejo" ? [".forgejo/workflows", ".github/workflows"] : [".github/workflows"];
-  const ref = opts.ref ? `?ref=${encodeURIComponent(opts.ref)}` : "";
-
-  const candidates: ContentsEntry[] = [];
-  const seen = new Set<string>();
-  for (const dir of dirs) {
-    const { body } = await getJson(`${host.api}/repos/${owner}/${repo}/contents/${dir}${ref}`);
-    if (!Array.isArray(body)) continue;
-    for (const entry of body as ContentsEntry[]) {
-      if (entry.type === "file" && isYaml(entry.name) && !seen.has(entry.path)) {
-        seen.add(entry.path);
-        candidates.push(entry);
-      }
-    }
-  }
+  const tree = await listTree(host, owner, repo, ref, doFetch, headers, cfg.timeoutMs);
+  const candidates = tree.filter((e) => isCandidatePath(e.path));
 
-  const inputs: AuditInput[] = [];
+  const files: Array<{ path: string; content: string }> = [];
   let total = 0;
   for (const entry of candidates) {
-    if (inputs.length >= cfg.maxFiles) break;
-    if ((entry.size ?? 0) > cfg.maxBytesPerFile) continue; // skip oversize
-    const { body } = await getJson(`${host.api}/repos/${owner}/${repo}/contents/${entry.path}${ref}`);
-    const file = body as ContentsEntry | null;
-    if (!file?.content) continue;
-    const content = Buffer.from(file.content, (file.encoding as BufferEncoding) ?? "base64").toString("utf-8");
+    if (files.length >= cfg.maxFiles) break;
+    if ((entry.size ?? 0) > cfg.maxBytesPerFile) continue; // skip oversize when the host reports size
+    const content = await fetchFileContent(host, owner, repo, entry.path, ref, doFetch, headers, cfg.timeoutMs);
+    if (content === undefined) continue;
     if (content.length > cfg.maxBytesPerFile) continue;
     total += content.length;
-    if (total > cfg.maxTotalBytes) throw new FetchError("Repository CI files exceed the total size cap.");
-    inputs.push({ path: entry.path, content, lexicon: host.lexicon });
+    if (total > cfg.maxTotalBytes) throw new FetchError("Repository files exceed the total size cap.");
+    files.push({ path: entry.path, content });
   }
-  return inputs;
+  return files;
 }
 
 const SHA40 = /^[0-9a-f]{40}$/;
@@ -193,9 +303,10 @@ export async function resolveActionSha(
     const res = await doFetch(url, {
       headers: {
         Accept: "application/vnd.github+json",
+        "User-Agent": USER_AGENT,
         ...(opts.token ? { Authorization: `Bearer ${opts.token}` } : {}),
       },
-      redirect: "error",
+      redirect: "manual",
       signal: timeoutSignal(opts.timeoutMs ?? DEFAULTS.timeoutMs),
     });
     if (!res.ok) return undefined;
@@ -289,16 +400,16 @@ export async function resolveImageDigest(
   const manifestUrl = `https://${parsed.registry}/v2/${parsed.repository}/manifests/${encodeURIComponent(parsed.tag)}`;
 
   try {
-    let res = await doFetch(manifestUrl, { headers: { Accept: accept }, redirect: "error", signal: timeoutSignal(ms) });
+    let res = await doFetch(manifestUrl, { headers: { Accept: accept, "User-Agent": USER_AGENT }, redirect: "manual", signal: timeoutSignal(ms) });
     if (res.status === 401) {
       const tokenUrl = tokenUrlFromChallenge(res.headers.get("www-authenticate") ?? "");
       if (!tokenUrl) return undefined;
-      const tokRes = await doFetch(tokenUrl, { redirect: "error", signal: timeoutSignal(ms) });
+      const tokRes = await doFetch(tokenUrl, { headers: { "User-Agent": USER_AGENT }, redirect: "manual", signal: timeoutSignal(ms) });
       if (!tokRes.ok) return undefined;
       const tok = (await tokRes.json()) as { token?: string; access_token?: string };
       const bearer = tok.token ?? tok.access_token;
       if (!bearer) return undefined;
-      res = await doFetch(manifestUrl, { headers: { Accept: accept, Authorization: `Bearer ${bearer}` }, redirect: "error", signal: timeoutSignal(ms) });
+      res = await doFetch(manifestUrl, { headers: { Accept: accept, "User-Agent": USER_AGENT, Authorization: `Bearer ${bearer}` }, redirect: "manual", signal: timeoutSignal(ms) });
     }
     if (!res.ok) return undefined;
     const digest = res.headers.get("docker-content-digest");
@@ -331,7 +442,7 @@ export async function resolveRepoCommit(
       ? `${host.api}/projects/${encodeURIComponent(`${owner}/${repo}`)}/repository/commits?per_page=1`
       : `${host.api}/repos/${owner}/${repo}/commits?per_page=1&limit=1`;
   try {
-    const res = await doFetch(apiUrl, { headers, redirect: "error", signal: timeoutSignal(opts.timeoutMs ?? DEFAULTS.timeoutMs) });
+    const res = await doFetch(apiUrl, { headers, redirect: "manual", signal: timeoutSignal(opts.timeoutMs ?? DEFAULTS.timeoutMs) });
     if (!res.ok) return undefined;
     const body = (await res.json()) as Array<{ sha?: string; id?: string }>;
     if (!Array.isArray(body) || body.length === 0) return undefined;
@@ -342,30 +453,3 @@ export async function resolveRepoCommit(
   }
 }
 
-async function fetchGitlab(
-  host: HostConfig,
-  owner: string,
-  repo: string,
-  ref: string | undefined,
-  cfg: { maxBytesPerFile: number; maxTotalBytes: number; timeoutMs: number },
-  doFetch: typeof fetch,
-  headers: Record<string, string>,
-): Promise<AuditInput[]> {
-  const projectId = encodeURIComponent(`${owner}/${repo}`);
-  const refQ = `?ref=${encodeURIComponent(ref ?? "HEAD")}`;
-  const apiUrl = `${host.api}/projects/${projectId}/repository/files/${encodeURIComponent(".gitlab-ci.yml")}/raw${refQ}`;
-  let res: Response;
-  try {
-    res = await doFetch(apiUrl, { headers, redirect: "error", signal: timeoutSignal(cfg.timeoutMs) });
-  } catch (err) {
-    throw new FetchError(`Request failed: ${err instanceof Error ? err.message : String(err)}`);
-  }
-  if (res.status >= 300 && res.status < 400) throw new FetchError(`Refusing to follow redirect from ${apiUrl}`);
-  if (res.status === 404) return [];
-  if (!res.ok) throw new FetchError(`${apiUrl} returned ${res.status}`);
-  const content = await res.text();
-  if (content.length > cfg.maxBytesPerFile || content.length > cfg.maxTotalBytes) {
-    throw new FetchError("Pipeline file exceeds the size cap.");
-  }
-  return [{ path: ".gitlab-ci.yml", content, lexicon: "gitlab" }];
-}

package/src/audit/remote-discovery.test.ts

@@ -0,0 +1,80 @@
+import { describe, test, expect } from "vitest";
+import { fileURLToPath } from "url";
+import { readdirSync, readFileSync, statSync } from "fs";
+import { join, relative } from "path";
+import { fetchRepoFiles, FetchError } from "./fetch";
+import { discoverByDetection, classifyFiles } from "./discover";
+import { loadAuditPlugins } from "./discover";
+
+const MIXED = fileURLToPath(new URL("../cli/commands/__fixtures__/audit-mixed", import.meta.url));
+
+/** Read a dir into relative-path → content (the "repo" a mock will serve). */
+function readDir(root: string): Record<string, string> {
+  const out: Record<string, string> = {};
+  const walk = (dir: string) => {
+    for (const e of readdirSync(dir, { withFileTypes: true })) {
+      const full = join(dir, e.name);
+      if (e.isDirectory()) walk(full);
+      else out[relative(root, full)] = readFileSync(full, "utf-8");
+    }
+  };
+  walk(root);
+  return out;
+}
+
+/** A GitHub-shaped mock: repo-info default_branch, recursive git/trees, base64 contents. */
+function mockGithub(files: Record<string, string>): typeof fetch {
+  const b64 = (s: string) => Buffer.from(s, "utf-8").toString("base64");
+  return (async (url: string | URL | Request) => {
+    const u = String(url);
+    if (u.includes("/git/trees/")) {
+      const tree = Object.keys(files).map((path) => ({ path, type: "blob", size: files[path].length }));
+      return new Response(JSON.stringify({ tree }), { status: 200 });
+    }
+    const cm = u.match(/\/contents\/(.+?)\?/);
+    if (cm) {
+      const path = decodeURIComponent(cm[1]);
+      const content = files[path];
+      if (content === undefined) return new Response("not found", { status: 404 });
+      return new Response(JSON.stringify({ path, type: "file", content: b64(content), encoding: "base64" }), { status: 200 });
+    }
+    if (/\/repos\/[^/]+\/[^/]+(\?|$)/.test(u)) return new Response(JSON.stringify({ default_branch: "main" }), { status: 200 });
+    return new Response("not found", { status: 404 });
+  }) as unknown as typeof fetch;
+}
+
+const targets = (inputs: { lexicon: string; path: string }[]) => inputs.map((i) => `${i.lexicon}:${i.path}`).sort();
+
+describe("remote audit covers all lexicons (not just CI)", () => {
+  test("a URL audit detects github + k8s + docker + aws in one repo", async () => {
+    const plugins = await loadAuditPlugins();
+    const files = await fetchRepoFiles("https://github.com/acme/widgets", { fetchImpl: mockGithub(readDir(MIXED)) });
+    const lexicons = new Set(classifyFiles(files, plugins).map((i) => i.lexicon));
+    expect([...lexicons].sort()).toEqual(["aws", "docker", "github", "k8s"]);
+  });
+
+  test("remote classification matches a local audit of the same repo (parity)", async () => {
+    const plugins = await loadAuditPlugins();
+    const local = discoverByDetection(MIXED, plugins);
+    const remote = classifyFiles(await fetchRepoFiles("https://github.com/acme/widgets", { fetchImpl: mockGithub(readDir(MIXED)) }), plugins);
+    expect(targets(remote)).toEqual(targets(local));
+  });
+
+  test("caps the number of files fetched", async () => {
+    const files = await fetchRepoFiles("https://github.com/acme/widgets", { fetchImpl: mockGithub(readDir(MIXED)), maxFiles: 1 });
+    expect(files.length).toBe(1);
+  });
+
+  test("rejects a non-allowlisted host before any fetch", async () => {
+    await expect(fetchRepoFiles("https://evil.example.com/o/r")).rejects.toThrow(/Host not allowed/);
+  });
+
+  test("refuses to follow a redirect on the tree request", async () => {
+    const impl = (async (url: string | URL | Request) => {
+      const u = String(url);
+      if (u.includes("/git/trees/")) return new Response(null, { status: 302 });
+      return new Response(JSON.stringify({ default_branch: "main" }), { status: 200 });
+    }) as unknown as typeof fetch;
+    await expect(fetchRepoFiles("https://github.com/acme/widgets", { fetchImpl: impl })).rejects.toThrow(/redirect/i);
+  });
+});

package/src/audit/report-html.ts

@@ -9,7 +9,7 @@
  */
 
 import type { AuditFinding } from "./core";
-import { ruleDocUrl } from "./catalog";
+import { ruleDocUrl, type RuleMeta } from "./catalog";
 import { buildReportModel, buildReportJson, type AuditSnapshot, type BuildModelOptions, type EnrichedFinding, type GuidanceCluster, type QuickWinFile, type ReportCounts } from "./report-model";
 
 export type { AuditSnapshot } from "./report-model";
@@ -34,7 +34,7 @@ export interface RenderHtmlOptions extends BuildModelOptions {
 }
 
 const DEFAULT_ACCENT = "#7c3aed";
-const DEFAULT_TITLE = "CI Security Audit";
+const DEFAULT_TITLE = "chant audit";
 const DEFAULT_FOOTER = 'Generated by <a href="https://intentius.io/chant/cli/audit/">chant audit</a>.';
 
 function esc(s: string): string {
@@ -46,6 +46,13 @@ function ruleLink(id: string): string {
   return `<a class="rule-id" href="${esc(ruleDocUrl(id))}">${esc(id)}</a>`;
 }
 
+/** External backing for a merge-worthy rule (OSSF Scorecard, CIS, vendor docs). */
+function authorityLinks(meta: RuleMeta): string {
+  if (!meta.authority?.length) return "";
+  const links = meta.authority.map((a) => `<a href="${esc(a.url)}">${esc(a.name)}</a>`).join(", ");
+  return ` <span class="muted">per ${links}</span>`;
+}
+
 function renderDiff(diff: string): string {
   const rows = diff
     .split("\n")
@@ -60,11 +67,11 @@ function renderDiff(diff: string): string {
 function renderQuickWins(files: QuickWinFile[]): string {
   const cards = files
     .map((qw) => {
-      const chips = qw.addressed.map((m) => `<span class="chip">${ruleLink(m.id)} ${esc(m.title)}</span>`).join(" ");
+      const chips = qw.addressed.map((m) => `<span class="chip">${ruleLink(m.id)} ${esc(m.title)}${authorityLinks(m)}</span>`).join(" ");
       const diff = qw.diff ? renderDiff(qw.diff) : "";
       const needs = qw.needsInput.length
         ? `<div class="needs"><strong>Needs a value to auto-patch:</strong><ul>${qw.needsInput
-            .map((f) => `<li>${ruleLink(f.checkId)}${f.entity ? ` (<code>${esc(f.entity)}</code>)` : ""} — ${esc(f.meta.remediation)}</li>`)
+            .map((f) => `<li>${ruleLink(f.checkId)}${f.entity ? ` (<code>${esc(f.entity)}</code>)` : ""} — ${esc(f.meta.remediation)}${authorityLinks(f.meta)}</li>`)
             .join("")}</ul></div>`
         : "";
       return `<div class="card"><div class="card-head"><code class="file">${esc(qw.file)}</code> ${chips}</div>${diff}${needs}</div>`;
@@ -82,7 +89,7 @@ function renderNeedsReview(clusters: GuidanceCluster[], n: number): string {
           const locs = findings
             .map((f) => `<li><code>${esc(f.file)}</code>${f.entity ? ` (<code>${esc(f.entity)}</code>)` : ""} — ${esc(f.message)}</li>`)
             .join("");
-          return `<div class="rule"><div><span class="sev ${findings[0].severity}"></span><strong>${ruleLink(meta.id)}</strong> — ${esc(meta.title)}. <span class="muted">${esc(meta.remediation)}</span></div><ul>${locs}</ul></div>`;
+          return `<div class="rule"><div><span class="sev ${findings[0].severity}"></span><strong>${ruleLink(meta.id)}</strong> — ${esc(meta.title)}. <span class="muted">${esc(meta.remediation)}</span>${authorityLinks(meta)}</div><ul>${locs}</ul></div>`;
         })
         .join("");
       return `<div class="cluster"><h3>${head}</h3>${rules}</div>`;
@@ -101,6 +108,7 @@ function renderReportOnly(findings: EnrichedFinding[], n: number): string {
 function renderHeader(counts: ReportCounts, snapshot: AuditSnapshot | undefined, notes: string[]): string {
   const sev = `<span class="sev error"></span>${counts.errors} error <span class="sev warning"></span>${counts.warnings} warning <span class="sev info"></span>${counts.infos} info`;
   const tiers = `<span class="chip">${counts.quickWin} quick-win</span> <span class="chip">${counts.needsReview} needs-review</span> <span class="chip">${counts.reportOnly} hygiene</span>`;
+  const cats = `<span class="chip">${counts.security} security</span> <span class="chip">${counts.correctness} correctness</span> <span class="chip">${counts.bestPractice} best-practice</span>`;
   const meta: string[] = [];
   if (snapshot) {
     if (snapshot.host) meta.push(esc(snapshot.host));
@@ -113,7 +121,7 @@ function renderHeader(counts: ReportCounts, snapshot: AuditSnapshot | undefined,
     meta.push(`chant ${esc(snapshot.toolVersion)}`);
   }
   const noteHtml = notes.map((n) => `<div class="note">${esc(n)}</div>`).join("");
-  return `<div class="summary"><div class="meta">${meta.join(" · ")}</div><div class="counts">${sev}</div><div class="tiers">${tiers}</div>${noteHtml}</div>`;
+  return `<div class="summary"><div class="meta">${meta.join(" · ")}</div><div class="counts">${sev}</div><div class="tiers">${tiers}</div><div class="tiers">${cats}</div>${noteHtml}</div>`;
 }
 
 const STYLES = `

package/src/audit/report-model.ts

@@ -6,7 +6,7 @@
  */
 
 import type { AuditFinding } from "./core";
-import { RULE_CATALOG, ruleDocUrl, type Authority, type FixKind, type RuleMeta, type Tier } from "./catalog";
+import { RULE_CATALOG, ruleDocUrl, type Authority, type Category, type FixKind, type RuleMeta, type Tier } from "./catalog";
 import { proveFix, unifiedDiff, type ProveOptions } from "./proof";
 import type { Severity } from "../lint/rule";
 
@@ -16,6 +16,8 @@ import type { Severity } from "../lint/rule";
  * major. Consumers should check the major and ignore unknown fields. See
  * `docs/cli/audit`.
  */
+// Additive changes (new fields like `category`, #415) keep the same version per
+// the stability contract; only renamed/removed fields bump it.
 export const REPORT_SCHEMA_VERSION = "1.0";
 
 export const SEVERITY_WEIGHT: Record<Severity, number> = { error: 0, warning: 1, info: 2 };
@@ -55,6 +57,10 @@ export interface ReportCounts {
   errors: number;
   warnings: number;
   infos: number;
+  /** Findings by category (#415) — what kind of issue, not how confident the fix. */
+  security: number;
+  correctness: number;
+  bestPractice: number;
 }
 
 export interface ReportModel {
@@ -88,6 +94,8 @@ export interface SerializedFinding {
   lexicon: string;
   tier: Tier;
   fixKind: FixKind;
+  /** What kind of finding this is (security / correctness / best-practice). */
+  category: Category;
   title: string;
   remediation: string;
   authority: Authority[];
@@ -237,6 +245,9 @@ export function buildReportModel(findings: AuditFinding[], opts: BuildModelOptio
     errors: shown.filter((f) => f.severity === "error").length,
     warnings: shown.filter((f) => f.severity === "warning").length,
     infos: shown.filter((f) => f.severity === "info").length,
+    security: shown.filter((f) => f.meta.category === "security").length,
+    correctness: shown.filter((f) => f.meta.category === "correctness").length,
+    bestPractice: shown.filter((f) => f.meta.category === "best-practice").length,
   };
 
   return {
@@ -266,6 +277,7 @@ export function buildReportJson(findings: AuditFinding[], opts: { snapshot?: Aud
       lexicon: f.lexicon,
       tier: f.meta.tier,
       fixKind: f.meta.fixKind,
+      category: f.meta.category,
       title: f.meta.title,
       remediation: f.meta.remediation,
       authority: f.meta.authority ?? [],

package/src/audit/report.test.ts

@@ -31,7 +31,9 @@ describe("renderMarkdown — reworked structure", () => {
   test("quick wins show a real combined diff when file content is provided", () => {
     const out = renderMarkdown(FINDINGS, { files: [{ path: ".github/workflows/ci.yml", content: CI }] });
     expect(out).toContain("## Quick wins (deterministic)");
-    expect(out).toContain("Addresses [GHA033](https://intentius.io/chant/lint-rules/audit-rules/#gha033) (Blanket write-all permissions):");
+    expect(out).toContain("Addresses [GHA033](https://intentius.io/chant/lint-rules/audit-rules/#gha033) (Blanket write-all permissions)");
+    // merge-worthy findings cite their external authority (#351 links surfaced in the layout)
+    expect(out).toContain("per [OSSF Scorecard — Token-Permissions](https://github.com/ossf/scorecard");
     expect(out).toContain("```diff");
     expect(out).toContain("-permissions: write-all");
     expect(out).toContain("+permissions:");

package/src/audit/report.ts

@@ -11,7 +11,7 @@
  */
 
 import type { AuditFinding } from "./core";
-import { ruleDocUrl } from "./catalog";
+import { ruleDocUrl, type RuleMeta } from "./catalog";
 import type { ProveOptions } from "./proof";
 import { buildReportModel, type EnrichedFinding, type GuidanceCluster, type QuickWinFile } from "./report-model";
 
@@ -20,6 +20,12 @@ function ruleLink(id: string): string {
   return `[${id}](${ruleDocUrl(id)})`;
 }
 
+/** External backing for a merge-worthy rule (OSSF Scorecard, CIS, vendor docs). */
+function authorityLinks(meta: RuleMeta): string {
+  if (!meta.authority?.length) return "";
+  return ` — per ${meta.authority.map((a) => `[${a.name}](${a.url})`).join(", ")}`;
+}
+
 export interface RenderOptions {
   /** Repo URL or path shown in the header. */
   target?: string;
@@ -42,14 +48,14 @@ function renderQuickWins(files: QuickWinFile[]): string[] {
   for (const qw of files) {
     lines.push(`### \`${qw.file}\``);
     if (qw.diff) {
-      const labels = qw.addressed.map((m) => `${ruleLink(m.id)} (${m.title})`).join(", ");
+      const labels = qw.addressed.map((m) => `${ruleLink(m.id)} (${m.title})${authorityLinks(m)}`).join(", ");
       lines.push("", `Addresses ${labels}:`, "", "```diff", qw.diff, "```");
     }
     if (qw.needsInput.length > 0) {
       lines.push("", "Needs a value before it can be auto-patched:");
       for (const f of qw.needsInput) {
         const where = f.entity ? ` (\`${f.entity}\`)` : "";
-        lines.push(`- **${ruleLink(f.checkId)}**${where} — ${f.meta.remediation}`);
+        lines.push(`- **${ruleLink(f.checkId)}**${where} — ${f.meta.remediation}${authorityLinks(f.meta)}`);
       }
     }
     lines.push("");
@@ -62,7 +68,7 @@ function renderNeedsReview(clusters: GuidanceCluster[]): string[] {
   for (const cluster of clusters) {
     lines.push(`### ${cluster.url ? `[${cluster.name}](${cluster.url})` : cluster.name}`, "");
     for (const { meta, findings } of cluster.rules) {
-      lines.push(`- **${ruleLink(meta.id)}** — ${meta.title} (${findings[0].severity}). ${meta.remediation}`);
+      lines.push(`- **${ruleLink(meta.id)}** — ${meta.title} (${findings[0].severity}). ${meta.remediation}${authorityLinks(meta)}`);
       for (const f of findings) {
         const where = f.entity ? `\`${f.file}\` (\`${f.entity}\`)` : `\`${f.file}\``;
         lines.push(`  - ${where} — ${escapeCell(f.message)}`);
@@ -87,7 +93,7 @@ export function renderMarkdown(findings: AuditFinding[], opts: RenderOptions = {
   const model = buildReportModel(findings, opts);
   const { counts } = model;
 
-  const lines: string[] = ["# CI security audit"];
+  const lines: string[] = ["# chant audit"];
   if (opts.target) lines.push("", `Target: ${opts.target}`);
   lines.push("");
   for (const note of opts.notes ?? []) lines.push(`> Note: ${note}`, "");
@@ -102,6 +108,8 @@ export function renderMarkdown(findings: AuditFinding[], opts: RenderOptions = {
       `${counts.quickWin} quick-win, ${counts.needsReview} needs-review, ${counts.reportOnly} report-only ` +
       `(${counts.errors} error, ${counts.warnings} warning, ${counts.infos} info).`,
     "",
+    `By category: ${counts.security} security, ${counts.correctness} correctness, ${counts.bestPractice} best-practice.`,
+    "",
   );
 
   if (model.quickWins.length > 0) lines.push(...renderQuickWins(model.quickWins));

package/src/cli/commands/__fixtures__/audit-mixed/.github/workflows/ci.yml

@@ -0,0 +1,5 @@
+on: push
+permissions: write-all
+jobs:
+  build:
+    runs-on: ubuntu-latest

package/src/cli/commands/__fixtures__/audit-mixed/Dockerfile

@@ -0,0 +1,2 @@
+FROM ubuntu
+RUN apt-get update

package/src/cli/commands/__fixtures__/audit-mixed/cfn/template.json

@@ -0,0 +1 @@
+{"AWSTemplateFormatVersion":"2010-09-09","Resources":{"B":{"Type":"AWS::S3::Bucket"}}}

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

@@ -0,0 +1,12 @@
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: x
+spec:
+  template:
+    spec:
+      containers:
+        - name: c
+          image: nginx:latest
+          securityContext:
+            privileged: true