@intentius/chant 0.124.45 → 0.124.48

package/src/capabilities/catalog.ts

@@ -0,0 +1,230 @@
+/**
+ * The capability catalog (#4375): the rule files core ships, the packs
+ * lexicons contribute, and the engine that evaluates one over a graph.
+ *
+ * Rules are data: `aws.paths` beside this module, read at run time. It serves
+ * every lexicon that maps AWS resources onto the view (the aws lexicon's
+ * CloudFormation kinds and the terraform lexicon's AWS provider types), so it
+ * lives here rather than in either lexicon. Each lexicon ships its mapping
+ * (data) and, where it needs one, an adapter (code), as a `CapabilityPack` on
+ * its plugin.
+ */
+import { readFileSync } from "node:fs";
+import type { GraphIR } from "../graph-ir";
+import { parseRules, ruleDependencies, type Literal, type Rule } from "./language";
+import { CapabilityEngine } from "./matcher";
+import { buildView, mergeMappings, type CapabilityMapping, type CapabilityPack, type View } from "./view";
+import base from "./base-mappings.json" with { type: "json" };
+
+/** The rule files core ships, by name. */
+const RULE_FILES = ["aws.paths"] as const;
+
+let rulesCache: { rules: Rule[]; sources: Map<string, string> } | undefined;
+
+/** Every rule core ships, parsed, with the file each came from. */
+export function shippedRules(): { rules: Rule[]; sources: Map<string, string> } {
+  if (rulesCache) return rulesCache;
+  const rules: Rule[] = [];
+  const sources = new Map<string, string>();
+  for (const file of RULE_FILES) {
+    const text = readFileSync(new URL(`./${file}`, import.meta.url), "utf-8");
+    for (const r of parseRules(text)) {
+      rules.push(r);
+      sources.set(r.name, file);
+    }
+  }
+  rulesCache = { rules, sources };
+  return rulesCache;
+}
+
+/** The mappings core's folds need, for a graph read without its lexicon's plugin. */
+export function basePacks(): CapabilityPack[] {
+  return (base as unknown as { mappings: CapabilityMapping[] }).mappings.map((mapping) => ({ mapping }));
+}
+
+const registered: CapabilityPack[] = [];
+
+/**
+ * Register a lexicon's pack for callers that hold no plugin list (the folds,
+ * a test). A plugin's `capabilityPack` reaches search without this.
+ */
+export function registerCapabilityPack(pack: CapabilityPack): void {
+  if (!registered.includes(pack)) registered.push(pack);
+}
+
+/** Base packs, registered packs, then the packs given: later ones extend earlier ones. */
+export function resolvePacks(packs: CapabilityPack[] = []): CapabilityPack[] {
+  return [...basePacks(), ...registered, ...packs.filter((p) => !registered.includes(p))];
+}
+
+const engines = new WeakMap<GraphIR, CapabilityEngine>();
+
+/**
+ * The capability engine for a graph, built once per graph object. Packs
+ * passed on the first call for a graph are the ones it uses.
+ */
+export function capabilityEngine(ir: GraphIR, packs: CapabilityPack[] = []): CapabilityEngine {
+  let e = engines.get(ir);
+  if (!e) {
+    e = new CapabilityEngine(buildView(ir, resolvePacks(packs)), shippedRules().rules);
+    engines.set(ir, e);
+  }
+  return e;
+}
+
+/** Bind a graph to the packs its search was given, before anything asks for a capability. */
+export function attachCapabilities(ir: GraphIR, packs: CapabilityPack[]): CapabilityEngine {
+  engines.delete(ir);
+  return capabilityEngine(ir, packs);
+}
+
+/**
+ * Bind a graph to a view built elsewhere (#4378): a workspace's composed
+ * view, which each member's own chant mapped. The rules are this chant's.
+ */
+export function attachView(ir: GraphIR, view: View): CapabilityEngine {
+  const e = new CapabilityEngine(view, shippedRules().rules);
+  engines.set(ir, e);
+  return e;
+}
+
+/**
+ * Read `name` or `name(arg, ...)`, as a search term or an edge qualifier
+ * spells a capability. An argument is a number, `true`/`false`, or text,
+ * quoted or not.
+ */
+export function parseCapabilityCall(text: string): { name: string; args: (Literal | undefined)[] } | undefined {
+  const m = /^([A-Za-z_][\w-]*)(?:\((.*)\))?$/.exec(text.trim());
+  if (!m) return undefined;
+  const args = m[2] === undefined || m[2].trim() === ""
+    ? []
+    : m[2].split(",").map((a) => {
+        const s = a.trim();
+        if (s === "" || s === "_") return undefined;
+        if (/^-?\d+(\.\d+)?$/.test(s)) return Number(s);
+        if (s === "true" || s === "false") return s === "true";
+        return s.replace(/^"(.*)"$/, "$1");
+      });
+  return { name: m[1], args };
+}
+
+/** Public capabilities: those whose rule carries a `## meaning`. Helpers carry none. */
+export function isPublic(rule: Rule): boolean {
+  return rule.meta.meaning !== undefined;
+}
+
+/** Every label a rule needs, through the capabilities it uses, per alternative: any one alternative suffices. */
+function labelsNeeded(rule: Rule, byName: Map<string, Rule>, seen = new Set<string>()): string[][] {
+  if (seen.has(rule.name)) return [[]];
+  seen.add(rule.name);
+  const out: string[][] = [];
+  for (const alt of rule.alts) {
+    // A node of any one of its labels will do, so each label is an option.
+    let options: string[][] = alt.head.labels ? alt.head.labels.map((l) => [l]) : [[]];
+    const add = (more: string[][]): void => {
+      options = options.flatMap((o) => more.map((m) => [...o, ...m]));
+    };
+    for (const t of alt.head.tests) if (t.kind === "cap" && !t.negated) add(labelsNeeded(byName.get(t.cap)!, byName, new Set(seen)));
+    for (const s of alt.steps) {
+      if (s.negated) continue;
+      if (s.node.labels && s.min > 0) add(s.node.labels.map((l) => [l]));
+      for (const t of s.node.tests) if (t.kind === "cap" && !t.negated) add(labelsNeeded(byName.get(t.cap)!, byName, new Set(seen)));
+      if (s.min > 0) {
+        const edgeRules = s.names.map((n) => byName.get(n.name)).filter((r): r is Rule => !!r);
+        if (edgeRules.length === s.names.length) add(edgeRules.flatMap((r) => labelsNeeded(r, byName, new Set(seen))));
+      }
+    }
+    out.push(...options);
+  }
+  return out;
+}
+
+/**
+ * Whether a lexicon can supply a capability: its own statement when its
+ * mapping makes one, otherwise whether every label one alternative needs
+ * is one the mapping labels.
+ */
+export function lexiconSupport(
+  rule: Rule,
+  mapping: CapabilityMapping | undefined,
+  lexicon: string,
+): "supported" | { code: string; message: string } {
+  if (!mapping) {
+    return { code: "lexicon-has-no-mapping", message: `the ${lexicon} lexicon ships no capability mapping` };
+  }
+  const stated = mapping.unsupported?.[rule.name];
+  if (stated) return stated;
+  // A lexicon's mapping extends core's base mapping for it (the folds' kinds).
+  const own = mapping;
+  const baseFor = basePacks().find((p) => p.mapping.lexicon === own.lexicon)?.mapping;
+  if (baseFor) mapping = mergeMappings(baseFor, own);
+  const { rules } = shippedRules();
+  const byName = new Map(rules.map((r) => [r.name, r]));
+  const labels = new Set(
+    Object.values(mapping.labels ?? {}).map((s) => (typeof s === "string" ? s : s.label)),
+  );
+  // Statements and inline blocks are the adapter's own nodes.
+  labels.add("Statement");
+  for (const specs of Object.values(mapping.blocks ?? {})) for (const b of specs) labels.add(b.label);
+  const options = labelsNeeded(rule, byName);
+  if (options.some((o) => o.every((l) => labels.has(l)))) return "supported";
+  const missing = [...new Set(options.flatMap((o) => o.filter((l) => !labels.has(l))))];
+  return {
+    code: "capability-not-derivable",
+    message: `the ${lexicon} mapping labels no ${missing.join(" or ")}`,
+  };
+}
+
+/** The capabilities a rule uses, directly. */
+export function usesOf(rule: Rule): string[] {
+  const { rules } = shippedRules();
+  const names = new Set(rules.map((r) => r.name));
+  return [...ruleDependencies(rule)].filter((n) => names.has(n));
+}
+
+/** One capability as the `capabilities` document lists it (#4375). */
+export interface CapabilityEntry {
+  name: string;
+  meaning: string;
+  shape: "set" | "edge";
+  params: { name: string; optional: boolean; meaning: string }[];
+  /** The search term that asks for it: `cap:<name>` for a set, `->[cap=<name>]` for an edge. */
+  search: string;
+  answers: string[];
+  depth: "declared" | "live" | "either";
+  lexicons: Record<string, "supported" | { code: string; message: string }>;
+  notEvaluated: string[];
+  /** The capabilities and helpers its rule uses. */
+  uses: string[];
+  rule: string;
+}
+
+/**
+ * The catalog as the `capabilities` document carries it: every public
+ * capability, with whether each lexicon given can supply it, and the helper
+ * rules they use. `lexicons` maps each lexicon to its mapping, or to
+ * undefined when it ships none.
+ */
+export function capabilityCatalog(lexicons: Record<string, CapabilityMapping | undefined>): {
+  capabilities: CapabilityEntry[];
+  helpers: { name: string; rule: string }[];
+} {
+  const { rules } = shippedRules();
+  const list = (s: string | undefined): string[] =>
+    (s ?? "").split(/\n|;/).map((x) => x.trim()).filter(Boolean);
+  const capabilities = rules.filter(isPublic).map((r): CapabilityEntry => ({
+    name: r.name,
+    meaning: r.meta.meaning,
+    shape: r.vars.length === 1 ? "set" : "edge",
+    params: r.params.map((p) => ({ name: p.name, optional: p.optional, meaning: r.meta[`param-${p.name}`] ?? "" })),
+    search: r.vars.length === 1 ? `cap:${r.name}` : `->[cap=${r.name}]`,
+    answers: (r.meta.answers ?? "").split("\n").map((x) => x.trim()).filter(Boolean),
+    depth: (r.meta.depth ?? "declared") as CapabilityEntry["depth"],
+    lexicons: Object.fromEntries(Object.entries(lexicons).map(([lex, m]) => [lex, lexiconSupport(r, m, lex)])),
+    notEvaluated: list(r.meta["not-evaluated"]),
+    uses: usesOf(r),
+    rule: r.text,
+  }));
+  const helpers = rules.filter((r) => !isPublic(r)).map((r) => ({ name: r.name, rule: r.text }));
+  return { capabilities, helpers };
+}

package/src/capabilities/language.test.ts

@@ -0,0 +1,191 @@
+/**
+ * The capability rule language and its matcher (#4375), over hand-built
+ * views: what each construct means, independent of any lexicon.
+ */
+import { describe, expect, it } from "vitest";
+import { parseRules, RuleSyntaxError } from "./language";
+import { CapabilityEngine, CapabilityError } from "./matcher";
+import { isPublic, lexiconSupport, parseCapabilityCall, shippedRules } from "./catalog";
+import type { View, ViewNode } from "./view";
+
+function view(nodes: [string, string, Record<string, unknown>?][], edges: [string, string, string][]): View {
+  const ns = new Map<string, ViewNode>(
+    nodes.map(([id, label, attrs]) => [id, { id, label, irId: id, lexicon: "test", attrs: attrs ?? {} }]),
+  );
+  return {
+    nodes: ns,
+    edges: edges.map(([from, name, to]) => ({ from, to, name, hops: [{ from, to, edge: name }] })),
+    lexicons: new Set(["test"]),
+  };
+}
+
+const keys = (m: Map<string, unknown>) => [...m.keys()].sort();
+const pairs = (rel: { out: Map<string, Map<string, unknown>> }) =>
+  [...rel.out].flatMap(([a, m]) => [...m.keys()].map((b) => `${a}>${b}`)).sort();
+
+describe("parseRules", () => {
+  it("reads sets, edges, parameters, alternatives, continuation lines and metadata", () => {
+    const rules = parseRules(`
+# a comment
+## meaning: a thing
+## answers: one
+## answers: two
+thing(x) := x:A|B[size >= 2, !gone]
+          | x:C
+link(a, b; p?, q) := a ->{0,1}via ->(e|f) b:B[n = $p] !<-blocked
+long(x) :=
+    x:A
+`);
+    expect(rules.map((r) => [r.name, r.vars, r.params, r.alts.length])).toEqual([
+      ["thing", ["x"], [], 2],
+      ["link", ["a", "b"], [{ name: "p", optional: true }, { name: "q", optional: false }], 1],
+      ["long", ["x"], [], 1],
+    ]);
+    expect(rules[0].meta).toEqual({ meaning: "a thing", answers: "one\ntwo" });
+    expect(rules[0].text).toBe("thing(x) := x:A|B[size >= 2, !gone]\n| x:C");
+    const steps = rules[1].alts[0].steps;
+    expect(steps.map((s) => [s.dir, s.negated, s.names.map((n) => n.name), s.min, s.max])).toEqual([
+      ["out", false, ["via"], 0, 1],
+      ["out", false, ["e", "f"], 1, 1],
+      ["in", true, ["blocked"], 1, 1],
+    ]);
+  });
+
+  it("refuses what it can't read, naming the line", () => {
+    expect(() => parseRules("a(x) := x:A\nb(x) := x[n ?? 1]")).toThrow(RuleSyntaxError);
+    expect(() => parseRules("a(x) := x:A\nb(x) := x[n ?? 1]")).toThrow(/line 2/);
+    expect(() => parseRules("| x:A")).toThrow(/needs a rule above it/);
+    expect(() => parseRules("a(x) := x:A\na(x) := x:B")).toThrow(/defined twice/);
+    expect(() => parseRules("a(x) := x !->{0,2}e")).toThrow(/negated step takes no depth/);
+  });
+
+  it("reads a capability call as search spells it", () => {
+    expect(parseCapabilityCall("open-ingress(22, tcp)")).toEqual({ name: "open-ingress", args: [22, "tcp"] });
+    expect(parseCapabilityCall("grants(s3:GetObject)")).toEqual({ name: "grants", args: ["s3:GetObject"] });
+    expect(parseCapabilityCall("reaches")).toEqual({ name: "reaches", args: [] });
+    expect(parseCapabilityCall("bad name")).toBeUndefined();
+  });
+});
+
+describe("the matcher", () => {
+  const v = view(
+    [
+      ["a", "A", { size: 3 }],
+      ["b", "A", { size: 1 }],
+      ["c", "B", { tags: ["x", "y"] }],
+      ["d", "B"],
+      ["e", "B"],
+    ],
+    [
+      ["a", "to", "c"],
+      ["c", "to", "d"],
+      ["d", "to", "e"],
+      ["b", "to", "d"],
+      ["e", "blocks", "d"],
+    ],
+  );
+
+  it("tests attributes, lists and labels", () => {
+    const e = new CapabilityEngine(v, parseRules(`
+big(x) := x:A[size >= 2]
+tagged(x) := x[tags in ("y")]
+absent(x) := x:B[!tags]
+`));
+    expect(keys(e.set("big"))).toEqual(["a"]);
+    expect(keys(e.set("tagged"))).toEqual(["c"]);
+    expect(keys(e.set("absent"))).toEqual(["d", "e"]);
+  });
+
+  it("walks a depth range, keeping the hops it took", () => {
+    const e = new CapabilityEngine(v, parseRules(`
+near(a, b) := a:A ->to b
+far(a, b) := a:A ->{2,} to b
+`));
+    expect(pairs(e.relation("near"))).toEqual(["a>c", "b>d"]);
+    expect(pairs(e.relation("far"))).toEqual(["a>d", "a>e", "b>e"]);
+    expect(e.relation("far").out.get("a")!.get("e")!.hops.map((h) => `${h.from}${h.to}`)).toEqual(["ac", "cd", "de"]);
+  });
+
+  it("negates a step and a capability test, and reads a capability that uses another", () => {
+    const e = new CapabilityEngine(v, parseRules(`
+unblocked(x) := x:B !<-blocks
+big(x) := x:A[size >= 2]
+small-reach(a, b) := a:A[!@big] ->{1,} to b[@unblocked]
+`));
+    expect(keys(e.set("unblocked"))).toEqual(["c", "e"]);
+    expect(pairs(e.relation("small-reach"))).toEqual(["b>e"]);
+  });
+
+  it("leaves out a test on a parameter nobody passed, and applies it when one is", () => {
+    const e = new CapabilityEngine(v, parseRules(`sized(x; min?) := x:A[size >= $min]`));
+    expect(keys(e.set("sized"))).toEqual(["a", "b"]);
+    expect(keys(e.set("sized", e.bind("sized", [2])))).toEqual(["a"]);
+    expect(() => e.bind("sized", [1, 2])).toThrow(/at most 1/);
+  });
+
+  it("closes a pattern on a variable it bound earlier", () => {
+    const loop = view([["p", "A"], ["q", "A"], ["r", "A"]], [["p", "to", "q"], ["q", "back", "p"], ["q", "back", "r"]]);
+    const e = new CapabilityEngine(loop, parseRules(`mutual(a, b) := a ->to b ->back a`));
+    expect(pairs(e.relation("mutual"))).toEqual(["p>q"]);
+  });
+
+  it("carries the evidence of each set a match relied on", () => {
+    const e = new CapabilityEngine(v, parseRules(`
+big(x) := x:A[size >= 2]
+from-big(a, b) := a[@big] ->to b
+`));
+    const ev = e.relation("from-big").out.get("a")!.get("c")!;
+    expect(ev.because.map((b) => [b.capability, b.id])).toEqual([["big", "a"]]);
+  });
+
+  it("refuses a capability that needs itself, an unknown one, and one used in the wrong shape", () => {
+    expect(() => new CapabilityEngine(v, parseRules(`a(x) := x[@nope]`))).toThrow(/no capability "nope"/);
+    expect(() => new CapabilityEngine(v, parseRules(`e(a, b) := a ->to b\ns(x) := x[@e]`))).toThrow(/is an edge, not a set/);
+    const self = new CapabilityEngine(v, parseRules(`loop(x) := x[@loop]`));
+    expect(() => self.set("loop")).toThrow(CapabilityError);
+  });
+});
+
+describe("the shipped catalog", () => {
+  const { rules } = shippedRules();
+  const pub = rules.filter(isPublic);
+
+  it("lists the 15 capabilities of the #4361 ruling (grants and reaches are one row)", () => {
+    expect(pub.map((r) => r.name)).toEqual([
+      "internet-facing",
+      "open-ingress",
+      "internet-reachable",
+      "attached-to-nothing",
+      "in-default-vpc",
+      "network",
+      "stores-data",
+      "holds-secret",
+      "encrypted-at-rest",
+      "publicly-readable",
+      "runs-as",
+      "can-assume",
+      "grants",
+      "reaches",
+      "exfiltrates",
+      "blast",
+    ]);
+  });
+
+  it("gives each a meaning, at least one answer and a depth", () => {
+    for (const r of pub) {
+      expect(r.meta.meaning, r.name).toBeTruthy();
+      expect(r.meta.answers, r.name).toBeTruthy();
+      expect(["declared", "live", "either"], r.name).toContain(r.meta.depth);
+      for (const p of r.params) expect(r.meta[`param-${p.name}`], `${r.name} ${p.name}`).toBeTruthy();
+    }
+  });
+
+  it("says a lexicon with no mapping can't supply any of them, and why a thin mapping can't", () => {
+    const rule = pub.find((r) => r.name === "grants")!;
+    expect(lexiconSupport(rule, undefined, "k8s")).toEqual({ code: "lexicon-has-no-mapping", message: "the k8s lexicon ships no capability mapping" });
+    const thin = lexiconSupport(rule, { lexicon: "x", labels: { "X::Bucket": "Bucket" } }, "x");
+    expect(thin).toMatchObject({ code: "capability-not-derivable" });
+    expect(lexiconSupport(rule, { lexicon: "x", labels: { "X::Role": "Role", "X::Policy": "Policy" } }, "x")).toBe("supported");
+    expect(lexiconSupport(rule, { lexicon: "x", unsupported: { grants: { code: "c", message: "m" } } }, "x")).toEqual({ code: "c", message: "m" });
+  });
+});