docs: Add 'ancestors' field to CEL playground (#820)

Author: russellhancox

docs/src/components/CELPlayground/autocompletion.ts

@@ -10,6 +10,7 @@ export interface CELCompletionItem {
   documentation?: string;
   insertText?: string;
   insertTextRules?: "insertAsSnippet";
+  v2Only?: boolean;
 }
 
 // CEL Macros - expanded at parse time into comprehensions
@@ -359,6 +360,7 @@ export const celWorkshopFunctions: CELCompletionItem[] = [
       "Returns REQUIRE_TOUCHID. The cooldown parameter specifies the number of minutes before TouchID is required again.",
     insertText: "require_touchid_with_cooldown_minutes(${1:minutes})",
     insertTextRules: "insertAsSnippet",
+    v2Only: true,
   },
   {
     label: "require_touchid_only_with_cooldown_minutes",
@@ -369,6 +371,7 @@ export const celWorkshopFunctions: CELCompletionItem[] = [
       "Returns REQUIRE_TOUCHID_ONLY. The cooldown parameter specifies the number of minutes before TouchID is required again.",
     insertText: "require_touchid_only_with_cooldown_minutes(${1:minutes})",
     insertTextRules: "insertAsSnippet",
+    v2Only: true,
   },
 ];
 
@@ -697,6 +700,11 @@ export interface CELVariable {
   name: string;
   type: CELVariableType;
   documentation?: string;
+  dynamic?: boolean;
+  v2Only?: boolean;
+  // For list-type variables, describes the fields available on each element
+  // (used for completions inside comprehensions like ancestors.filter(a, a.))
+  itemFields?: CELVariable[];
 }
 
 // Track registration state to prevent duplicate registrations
@@ -766,8 +774,13 @@ export function registerCELLanguage(
 
   // Build a map of variable names to types for quick lookup
   const variableTypes = new Map<string, CELVariableType>();
+  // Build a map of list variable names to their item fields
+  const listItemFields = new Map<string, CELVariable[]>();
   for (const v of variables) {
     variableTypes.set(v.name, v.type);
+    if (v.type === "list" && v.itemFields) {
+      listItemFields.set(v.name, v.itemFields);
+    }
   }
 
   // Build general completion items (not after a dot)
@@ -920,17 +933,19 @@ export function registerCELLanguage(
           endColumn: position.column,
         });
 
-        // Check if we're typing after a dot (e.g., "args." or "target.signing_time.")
-        // Captures the full dotted path before the final dot
+        // Check if we're typing after a dot (e.g., "args.", "target.signing_time.", "ancestors[0].")
+        // Captures the full expression before the final dot, including bracket indexing
         const dotMatch = textUntilPosition.match(
-          /([\w]+(?:\.[\w]+)*)\.[\w]*$/,
+          /([\w]+(?:\[[^\]]*\])*(?:\.[\w]+(?:\[[^\]]*\])*)*)\.[\w]*$/,
         );
         if (dotMatch) {
           const varPath = dotMatch[1];
-          const varType = variableTypes.get(varPath);
+          // Strip bracket indices to resolve the base variable name (e.g. "ancestors[0]" → "ancestors")
+          const basePath = varPath.replace(/\[[^\]]*\]/g, "");
+          const varType = variableTypes.get(basePath);
 
           // Check for sub-field completions (e.g., "target." → "signing_time")
-          const prefix = varPath + ".";
+          const prefix = basePath + ".";
           const fieldCompletions: any[] = [];
           const seenFields = new Set<string>();
 
@@ -961,6 +976,21 @@ export function registerCELLanguage(
               suggestions: [...fieldCompletions, ...mapMethodCompletions],
             };
           } else if (varType === "list") {
+            // If indexing into the list (e.g. "ancestors[0]."), offer item fields
+            if (varPath !== basePath) {
+              const itemFields = listItemFields.get(basePath);
+              if (itemFields) {
+                return {
+                  suggestions: itemFields.map((f) => ({
+                    label: f.name,
+                    kind: monaco.languages.CompletionItemKind.Field,
+                    insertText: f.name,
+                    detail: f.type,
+                    documentation: f.documentation,
+                  })),
+                };
+              }
+            }
             return {
               suggestions: [...fieldCompletions, ...listMethodCompletions],
             };
@@ -977,6 +1007,26 @@ export function registerCELLanguage(
             return { suggestions: fieldCompletions };
           }
 
+          // Check if this is a comprehension iteration variable
+          // e.g. "ancestors.filter(a, a." → varPath is "a", look back for "ancestors.filter(a,"
+          const comprehensionMatch = textUntilPosition.match(
+            /([\w]+)\.(?:all|exists|exists_one|filter|map|sortBy)\(\s*(\w+)\s*,/,
+          );
+          if (comprehensionMatch && comprehensionMatch[2] === varPath) {
+            const listName = comprehensionMatch[1];
+            const itemFields = listItemFields.get(listName);
+            if (itemFields) {
+              const itemFieldCompletions = itemFields.map((f) => ({
+                label: f.name,
+                kind: monaco.languages.CompletionItemKind.Field,
+                insertText: f.name,
+                detail: f.type,
+                documentation: f.documentation,
+              }));
+              return { suggestions: itemFieldCompletions };
+            }
+          }
+
           // No type info: return fields if any, otherwise all methods as fallback
           if (fieldCompletions.length > 0) {
             return { suggestions: fieldCompletions };

docs/src/components/CELPlayground/constants.ts

@@ -3,10 +3,10 @@ import { ReturnValueSchema as V2ReturnValueSchema } from "@buf/northpolesec_prot
 import { CELVariable } from "./autocompletion";
 
 export const VARIABLES: CELVariable[] = [
-  { name: "envs", type: "map", documentation: "Environment variables" },
-  { name: "args", type: "list", documentation: "Command line arguments" },
-  { name: "euid", type: "int", documentation: "Effective user ID" },
-  { name: "cwd", type: "string", documentation: "Current working directory" },
+  { name: "envs", type: "map", dynamic: true, documentation: "Environment variables" },
+  { name: "args", type: "list", dynamic: true, documentation: "Command line arguments" },
+  { name: "euid", type: "int", dynamic: true, documentation: "Effective user ID" },
+  { name: "cwd", type: "string", dynamic: true, documentation: "Current working directory" },
   {
     name: "target.signing_id",
     type: "string",
@@ -45,17 +45,27 @@ export const VARIABLES: CELVariable[] = [
     type: "string",
     documentation: "Require Touch ID only policy constant",
   },
+  {
+    name: "ancestors",
+    type: "list",
+    dynamic: true,
+    v2Only: true,
+    documentation:
+      "List of ancestor processes in the execution chain. Each ancestor has signing_id, team_id, path, and cdhash fields.",
+    itemFields: [
+      {
+        name: "signing_id",
+        type: "string",
+        documentation:
+          "Signing ID of the ancestor binary, prefixed with Team ID or 'platform'",
+      },
+      { name: "team_id", type: "string", documentation: "Team ID from code signature" },
+      { name: "path", type: "string", documentation: "Path to the ancestor binary" },
+      { name: "cdhash", type: "string", documentation: "Code directory hash" },
+    ],
+  },
 ];
 
-export const DYNAMIC_FIELDS = ["args", "envs", "euid", "cwd"] as const;
-
-export const V2_ONLY_FUNCTIONS = [
-  "require_touchid_with_cooldown_minutes",
-  "require_touchid_only_with_cooldown_minutes",
-] as const;
-
-export const FUNCTIONS = ["timestamp", ...V2_ONLY_FUNCTIONS] as const;
-
 // Build enum name→value and value→name maps from proto descriptors
 function enumEntries(schema: {
   values: readonly { name: string; number: number }[];
@@ -73,9 +83,3 @@ function enumEntries(schema: {
 export const v1Entries = enumEntries(V1ReturnValueSchema);
 export const v2Entries = enumEntries(V2ReturnValueSchema);
 
-export const CONSTANT_NAMES = Object.keys(v2Entries.nameToValue);
-
-// V2-only constant names (not in V1)
-export const V2_ONLY_CONSTANTS = new Set(
-  CONSTANT_NAMES.filter((name) => !(name in v1Entries.nameToValue)),
-);

docs/src/components/CELPlayground/eslogger.test.ts

@@ -46,6 +46,18 @@ describe("convertEsloggerEvent", () => {
     });
   });
 
+  it("always includes fake ancestors", () => {
+    const result = toObject(convertEsloggerEvent(MINIMAL_EXEC_EVENT));
+    expect(result.ancestors).toEqual([
+      {
+        signing_id: "platform:com.apple.Terminal",
+        team_id: "",
+        path: "/System/Applications/Utilities/Terminal.app/Contents/MacOS/Terminal",
+        cdhash: "",
+      },
+    ]);
+  });
+
   it("handles env values containing '='", () => {
     const event = JSON.stringify({
       event: {

docs/src/components/CELPlayground/eslogger.ts

@@ -68,10 +68,18 @@ export function convertEsloggerEvent(input: string): string {
     }
   }
 
-  // Make up signing times (eslogger doesn't include these)
+  // Make up signing times and ancestors (eslogger events don't include these)
   context.target.signing_time = "2025-06-01T00:00:00Z";
   context.target.secure_signing_time = "2025-06-01T00:00:00Z";
+  context.ancestors = [
+    {
+      signing_id: "platform:com.apple.Terminal",
+      team_id: "",
+      path: "/System/Applications/Utilities/Terminal.app/Contents/MacOS/Terminal",
+      cdhash: "",
+    },
+  ];
 
   const yaml = stringifyYAML(context);
-  return "# Note: signing times are fake — eslogger events don't include them\n" + yaml;
+  return "# Note: signing times and ancestors are fake — eslogger events don't include them\n" + yaml;
 }

docs/src/components/CELPlayground/eval.test.ts

@@ -91,6 +91,17 @@ describe("evaluate", () => {
     expect(result.isV2).toBe(true);
   });
 
+  it("detects V2 variable ancestors", () => {
+    const yaml = `ancestors:\n  - signing_id: "platform:com.apple.bash"\n    path: "/bin/bash"`;
+    const result = evaluate(
+      'ancestors.exists(a, a.signing_id == "platform:com.apple.bash")',
+      yaml,
+    );
+    expect(result.valid).toBe(true);
+    expect(result.isV2).toBe(true);
+    expect(result.cacheable).toBe(false);
+  });
+
   it("marks V1-only expressions as not V2", () => {
     const result = evaluate("ALLOWLIST", DEFAULT_YAML);
     expect(result.valid).toBe(true);

docs/src/components/CELPlayground/eval.ts

@@ -1,11 +1,11 @@
 import { Environment } from "@marcbachmann/cel-js";
 import { parse as parseYAML } from "yaml";
 import {
-  V2_ONLY_FUNCTIONS,
-  DYNAMIC_FIELDS,
-  V2_ONLY_CONSTANTS,
+  VARIABLES,
+  v1Entries,
   v2Entries,
 } from "./constants";
+import { celWorkshopFunctions } from "./autocompletion";
 
 
 export const DEFAULT_EXPRESSION = `target.signing_time >= timestamp('2025-05-31T00:00:00Z')`;
@@ -18,7 +18,12 @@ args:
 envs:
   HOME: "/Users/user"
 euid: 501
-cwd: "/Users/user"`;
+cwd: "/Users/user"
+ancestors:
+  - signing_id: "platform:com.apple.Terminal"
+    team_id: ""
+    path: "/System/Applications/Utilities/Terminal.app/Contents/MacOS/Terminal"
+    cdhash: "abc123"`;
 
 function buildEnvironment(): Environment {
   const env = new Environment({ unlistedVariablesAreDyn: true });
@@ -29,6 +34,7 @@ function buildEnvironment(): Environment {
   env.registerVariable("envs", "map");
   env.registerVariable("euid", "int");
   env.registerVariable("cwd", "string");
+  env.registerVariable("ancestors", "list");
 
   // Register all V2 enum constants (superset of V1)
   for (const [name, value] of Object.entries(v2Entries.nameToValue)) {
@@ -109,17 +115,17 @@ function usesV2Features(
   identifiers: Set<string>,
   calls: Set<string>,
 ): boolean {
-  for (const name of V2_ONLY_CONSTANTS) {
-    if (identifiers.has(name)) return true;
-  }
-  for (const fn of V2_ONLY_FUNCTIONS) {
-    if (calls.has(fn)) return true;
+  for (const name of Object.keys(v2Entries.nameToValue)) {
+    if (!(name in v1Entries.nameToValue) && identifiers.has(name)) return true;
   }
+  if (VARIABLES.some((v) => v.v2Only && identifiers.has(v.name))) return true;
+  if (celWorkshopFunctions.some((f) => f.v2Only && calls.has(f.label)))
+    return true;
   return false;
 }
 
 function isCacheable(identifiers: Set<string>): boolean {
-  return !DYNAMIC_FIELDS.some((field) => identifiers.has(field));
+  return !VARIABLES.some((v) => v.dynamic && identifiers.has(v.name));
 }
 
 export interface EvalResult {