@intentius/chant 0.124.13 → 0.124.14

package/dist/audit/core.js

@@ -0,0 +1,252 @@
+/**
+ * Audit core — run chant's CI security checks against arbitrary repo YAML.
+ *
+ * The post-synth security checks (`lexicons/<lex>/src/lint/post-synth/*.ts`)
+ * read the emitted workflow YAML from `ctx.outputs`, not the chant model
+ * (`ctx.entities`). So an auditor can feed *existing* repo YAML straight in as
+ * a synthetic output and run the real rules — no import-to-chant-model step.
+ *
+ * Each file is audited as its own `primary` output so single-document security
+ * checks (the merge-worthy tier: permissions, pinning, injection, secrets)
+ * fire on every workflow. Cross-file checks (e.g. duplicate workflow names)
+ * only see one file at a time here; that is acceptable because the security
+ * tier is per-document.
+ *
+ * Checks that read `ctx.entities` instead of `ctx.outputs` normally will not
+ * fire on audited YAML — the security tier is YAML-based, so this is by
+ * design. The exception is a lexicon that ships `auditEntities` (#1567):
+ * its classified files are parsed back into the entity graph (parse-to-graph),
+ * so the same graph-reading checks that fire on `chant build` fire on the
+ * audit too, with no output-reading rule variants to drift.
+ */
+import { basename } from "path";
+import { applyInlineSuppressions } from "../lint/suppressions.js";
+import { lexiconModulePath, lexiconPackagesToInstall, lexiconSourceLabel } from "../lexicon-module.js";
+const checksCache = new Map();
+const entitiesParserCache = new Map();
+function dedupeById(checks) {
+    const byId = new Map();
+    for (const check of checks) {
+        if (!byId.has(check.id))
+            byId.set(check.id, check);
+    }
+    return [...byId.values()];
+}
+/**
+ * Default provider: load the lexicon plugin(s) and return their post-synth
+ * checks. Forgejo workflows are GitHub-dialect YAML, so the GitHub security
+ * tier is run against them in addition to Forgejo's own checks.
+ */
+/** Thrown when a lexicon package the audit needs isn't installed. */
+export class MissingLexiconError extends Error {
+}
+async function load(names) {
+    try {
+        // Lazy import so that merely importing `auditFiles` doesn't pull in
+        // `cli/plugins` -> config loader -> the TypeScript compiler. A caller that
+        // supplies its own `checksProvider` (e.g. an edge/bundled deployment) never
+        // reaches this and never bundles that graph. See #408.
+        const { loadPlugins } = await import("../cli/plugins.js");
+        return await loadPlugins(names);
+    }
+    catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        // chant#2578 — a lexicon declared by path in chant.config.ts has no
+        // package: name its module and print no install line for it.
+        const pkgs = lexiconPackagesToInstall(names);
+        const paths = names.filter((n) => lexiconModulePath(n) !== undefined).map((n) => lexiconSourceLabel(n));
+        if (pkgs.length === 0) {
+            throw new MissingLexiconError(`Could not load the lexicon module ${paths.join(", ")} needed to audit ${names.join("/")} workflows.\n(${detail})`);
+        }
+        const fromPath = paths.length > 0 ? ` The lexicon module ${paths.join(", ")} is declared by path and has nothing to install.` : "";
+        throw new MissingLexiconError(`Missing lexicon package needed to audit ${names.join("/")} workflows. Install it with: npm i ${pkgs.join(" ")}${fromPath}\n(${detail})`);
+    }
+}
+async function defaultChecksProvider(lexicon) {
+    const cached = checksCache.get(lexicon);
+    if (cached)
+        return cached;
+    let checks;
+    if (lexicon === "forgejo") {
+        const [forgejo, github] = await load(["forgejo", "github"]);
+        checks = dedupeById([
+            ...(forgejo?.postSynthChecks?.() ?? []),
+            ...(github?.postSynthChecks?.() ?? []),
+        ]);
+    }
+    else {
+        const [plugin] = await load([lexicon]);
+        checks = plugin?.postSynthChecks?.() ?? [];
+    }
+    checksCache.set(lexicon, checks);
+    return checks;
+}
+/**
+ * Default provider for the parse-to-graph half (#1567): a lexicon that ships
+ * `auditEntities` gets its classified files parsed into `ctx.entities`. A
+ * lexicon without the hook (or one that fails to load — the checks provider
+ * already surfaced that) simply audits with an empty entity graph, as before.
+ */
+async function defaultEntitiesProvider(lexicon) {
+    if (entitiesParserCache.has(lexicon))
+        return entitiesParserCache.get(lexicon);
+    let parser;
+    try {
+        const [plugin] = await load([lexicon]);
+        const parse = plugin?.auditEntities?.bind(plugin);
+        if (parse)
+            parser = parse;
+    }
+    catch {
+        parser = undefined;
+    }
+    entitiesParserCache.set(lexicon, parser);
+    return parser;
+}
+/**
+ * Audit a set of CI files and return all findings. Pure with respect to the
+ * filesystem and network — callers supply file contents.
+ */
+export async function auditFiles(inputs, opts = {}) {
+    const provider = opts.checksProvider ?? defaultChecksProvider;
+    const entitiesProvider = opts.entitiesProvider ?? defaultEntitiesProvider;
+    const findings = [];
+    // Group by lexicon so each plugin's checks are resolved once.
+    const byLexicon = new Map();
+    for (const input of inputs) {
+        const list = byLexicon.get(input.lexicon) ?? [];
+        list.push(input);
+        byLexicon.set(input.lexicon, list);
+    }
+    for (const [lexicon, files] of byLexicon) {
+        const checks = (await provider(lexicon)).filter((c) => !c.auditOptIn || opts.enabledRules?.has(c.id));
+        if (checks.length === 0)
+            continue;
+        const parseEntities = await entitiesProvider(lexicon);
+        findings.push(...(await auditLexicon(lexicon, files, checks, parseEntities, opts.suppressionStats)));
+    }
+    return findings;
+}
+/** Label for findings that span more than one file (e.g. duplicate names). */
+export const CROSS_FILE = "(cross-file)";
+/**
+ * Each file as its own serialized output. Most lexicons get a SerializerResult
+ * (primary + basename-keyed files; docker filters `files` by name). The gcp
+ * checks require the output to be a raw string (`typeof output === "string"`),
+ * so gcp gets the content directly.
+ */
+function toOutput(file) {
+    if (file.files)
+        return { primary: file.content, files: file.files };
+    if (file.lexicon === "gcp")
+        return file.content;
+    return { primary: file.content, files: { [basename(file.path)]: file.content } };
+}
+function runChecks(checks, outputs, entities = new Map()) {
+    const buildResult = { outputs, entities, warnings: [], errors: [], sourceFileCount: outputs.size };
+    const ctx = { outputs, entities: buildResult.entities, buildResult };
+    const diags = [];
+    for (const check of checks) {
+        try {
+            diags.push(...check.check(ctx));
+        }
+        catch {
+            // A check that throws on unusual external YAML must not abort the audit.
+        }
+    }
+    // chant #2111: `rules` (for `ignorable: false`) is omitted, since `chant audit`
+    // has no project `lint.rules` to read here (see `applyInlineSuppressions`'s
+    // doc comment for why that's a deliberate scope line, not an oversight), so
+    // every rule id reads as ignorable, same as an unconfigured one everywhere.
+    return applyInlineSuppressions(diags, entities);
+}
+function diagKey(d) {
+    return `${d.checkId}\u0000${d.entity ?? ""}\u0000${d.message}`;
+}
+/**
+ * Merge per-file entity maps into one graph for the all-files pass. A key
+ * collision (the same entity name declared in two files) gets a `#n` suffix —
+ * so no declaration is silently dropped and duplicate-name checks keep both
+ * in view.
+ */
+function mergeEntities(maps) {
+    const merged = new Map();
+    for (const m of maps) {
+        for (const [key, entity] of m) {
+            let k = key;
+            for (let n = 2; merged.has(k); n++)
+                k = `${key}#${n}`;
+            merged.set(k, entity);
+        }
+    }
+    return merged;
+}
+/**
+ * Audit one lexicon's files with cross-file awareness.
+ *
+ * Two passes:
+ *  - **all-files** (every file in one context) is the source of truth — it lets
+ *    relational checks resolve (an Application sees its AppProject elsewhere; a
+ *    duplicate name is seen across files) and clears single-file false positives.
+ *  - **per-file** supplies the file each finding belongs to.
+ *
+ * A per-file finding is kept only if it survives in the all-files pass (drops
+ * cross-file-resolved false positives). An all-files finding with no per-file
+ * match is a genuine cross-file finding, labelled `CROSS_FILE`.
+ *
+ * When the lexicon supplies an entities parser (#1567), each pass also carries
+ * the entity graph parsed from its files — per file for the per-file pass, all
+ * files merged for the all-files pass — so entity-reading checks fire and
+ * cross-file facts (an Agent's Environment declared elsewhere, a name declared
+ * twice across the apply directory) resolve in the all-files pass. The parser
+ * may be async (a lexicon's own choice, e.g. a wasm-backed HCL parser); this
+ * function awaits each file's entities before either pass runs.
+ */
+async function auditLexicon(lexicon, files, checks, parseEntities, suppressionStats) {
+    const entitiesFor = async (file) => {
+        if (!parseEntities)
+            return new Map();
+        try {
+            return await parseEntities(file.content, {
+                path: file.path,
+                ...(file.dir !== undefined ? { dir: file.dir } : {}),
+                ...(file.baseDir !== undefined ? { baseDir: file.baseDir } : {}),
+            });
+        }
+        catch {
+            // The audit contract is "runs against any repo" — unparseable content
+            // contributes no entities, never a crash.
+            return new Map();
+        }
+    };
+    const perEntities = new Map(await Promise.all(files.map(async (f) => [f.path, await entitiesFor(f)])));
+    const perFindings = [];
+    const perKeys = new Set();
+    // chant #2111: meta findings (an expired/misplaced/denied suppression
+    // directive) are collected from the per-file pass only: the all-files pass
+    // below sees the same entities merged, so it would report the identical
+    // directive again. Counted the same way, once, here too.
+    const metaFindings = [];
+    for (const file of files) {
+        const { diagnostics: diags, suppressed, meta } = runChecks(checks, new Map([[file.path, toOutput(file)]]), perEntities.get(file.path));
+        if (suppressionStats)
+            suppressionStats.count += suppressed.length;
+        for (const m of meta) {
+            metaFindings.push({ checkId: m.checkId, severity: m.severity, message: m.message, file: m.file, lexicon, line: m.line });
+        }
+        for (const d of diags) {
+            perFindings.push({ checkId: d.checkId, severity: d.severity, message: d.message, file: file.path, lexicon: d.lexicon ?? lexicon, entity: d.entity, missing: d.missing });
+            perKeys.add(diagKey(d));
+        }
+    }
+    const allOutputs = new Map(files.map((f) => [f.path, toOutput(f)]));
+    const { diagnostics: allDiags } = runChecks(checks, allOutputs, mergeEntities([...perEntities.values()]));
+    const allKeys = new Set(allDiags.map(diagKey));
+    const out = perFindings.filter((f) => allKeys.has(diagKey(f)));
+    for (const d of allDiags) {
+        if (!perKeys.has(diagKey(d))) {
+            out.push({ checkId: d.checkId, severity: d.severity, message: d.message, file: CROSS_FILE, lexicon: d.lexicon ?? lexicon, entity: d.entity, missing: d.missing });
+        }
+    }
+    return [...out, ...metaFindings];
+}