@loophubs/agent-guard 0.2.0 → 0.4.0

package/src/interpreters.ts

@@ -0,0 +1,61 @@
+import type { Word } from "./record";
+
+// Per interpreter: the short flags after which the code follows, in the rest of the cluster when `glued` and in the next word otherwise,
+// and the flags whose value is the rest of the cluster, so a value such as `-rtime` does not read its last letter as a code flag.
+const flags: Record<string, { code: string; value: string; glued: boolean }> = {
+  python: { code: "c", value: "WX", glued: true },
+  python3: { code: "c", value: "WX", glued: true },
+  node: { code: "ep", value: "", glued: false },
+  bun: { code: "ep", value: "", glued: true },
+  ruby: { code: "e", value: "rICEix", glued: true },
+  perl: { code: "eE", value: "MmIidDCFx", glued: true },
+  php: { code: "rR", value: "dcfz", glued: true },
+  osascript: { code: "e", value: "", glued: true },
+  lua: { code: "e", value: "l", glued: true },
+  deno: { code: "", value: "", glued: false },
+};
+
+// The table entry a program name selects, ignoring a version suffix such as `python3.14`.
+export function interpreterName(name: string): string | undefined {
+  return [name, name.replace(/[\d.]+$/, "")].find((candidate) => candidate in flags);
+}
+
+// The code an interpreter runs from its command line: the word after a code flag, the value glued to `--eval=`, or deno's eval operand.
+export function interpreterCode(name: string, args: Word[]): string[] {
+  const { code, value, glued } = flags[name]!;
+  const found: string[] = [];
+  const take = (word: Word | undefined) => {
+    if (!word) return;
+    word.role = "code";
+    found.push(word.text);
+  };
+  if (name === "deno") {
+    // Flags such as `-p` and `--ext=ts` sit between `eval` and the code.
+    // `eval` follows the global flags and the value of a flag such as `--log-level debug`.
+    const operands = args.filter((word) => !word.text.startsWith("-"));
+    const at = operands.slice(0, 2).findIndex((word) => word.text === "eval");
+    if (at >= 0) for (const word of operands.slice(at + 1)) take(word);
+    return found;
+  }
+  for (let i = 0; i < args.length; i++) {
+    const text = args[i]!.text;
+    // node's --run names a package script; only php's takes code.
+    const long = (name === "php" ? /^--(eval|print|run)(=(.*))?$/s : /^--(eval|print)(=(.*))?$/s).exec(text);
+    if (long) {
+      if (long[2] === undefined) take(args[++i]);
+      else found.push(long[3]!);
+      continue;
+    }
+    if (!/^-[^-]/.test(text)) continue;
+    for (let k = 1; k < text.length; k++) {
+      if (value.includes(text[k]!)) break;
+      if (code.includes(text[k]!)) {
+        if (k < text.length - 1 && !glued) continue;
+        if (k < text.length - 1) found.push(text.slice(k + 1));
+        else take(args[++i]);
+        break;
+      }
+    }
+  }
+  return found;
+}

package/src/links.ts

@@ -1,64 +1,71 @@
-import { readlinkSync } from "node:fs";
-import { basename, dirname, resolve } from "node:path";
+import { readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
 
-import { absPath, expandHome, isAppdata, isSensitive } from "./paths";
-import type { Request, Word } from "./record";
-import { dataPrograms } from "./rules/appdata";
+import { isAppdata, isSensitive, unfirmlink } from "./paths";
+import { probes } from "./probes";
+import type { Target } from "./record";
 
-export function linkedRequest(req: Request): Request | undefined {
-  let changed = false;
-  const protectedPath = (path: string) => isAppdata(path, req.home) || isSensitive(path);
-  const linked = (value: string, cwd: string, quoted = false): string => {
-    const input = quoted ? value : expandHome(value, req.home);
-    const absolute = input.startsWith("/") ? input : `${cwd}/${input}`;
-    let path = "/";
-    let parts = absolute.split("/").filter(Boolean);
-    let followed = false;
-    let depth = 0;
-    while (parts.length) {
-      const part = parts.shift()!;
-      path = part === ".." ? dirname(path) : resolve(path, part);
-      // Do not ask the filesystem about a path inside a protected tree.
-      if (protectedPath(path)) {
-        changed = true;
-        return path;
-      }
-      let target: string;
-      try {
-        target = readlinkSync(path);
-      } catch {
-        continue;
-      }
-      if (++depth > 8) throw new Error("Symlink chain exceeds the agent guard limit");
-      const targetPath = target.startsWith("/") ? target : `${dirname(path)}/${target}`;
-      followed = true;
-      changed = true;
-      parts = [...targetPath.split("/").filter(Boolean), ...parts];
-      path = "/";
+// Errors that mean the path is not a link: it names a regular file or directory, or nothing (a component past NAME_MAX cannot exist). Any other
+// failure means the check did not run.
+export const notALink = ["EINVAL", "ENOENT", "ENOTDIR", "ENAMETOOLONG"];
+
+// The directories of the Data volume that are also reached from the root, in the kernel's own table. The kernel resolves `..` from one of them
+// in the root tree, and from any other directory of the Data volume in place. The table is a fixed system file, not a path taken from a command;
+// if it is missing the import fails and the guard denies.
+const firmlinks = new Set(
+  readFileSync("/usr/share/firmlinks", "utf8")
+    .split("\n")
+    .filter(Boolean)
+    .map((line) => `/system/volumes/data/${line.split("\t")[1]!.toLowerCase()}`),
+);
+
+// Follow the symlinks in an absolute path with readlink alone, so a link into a protected tree is judged by where it leads. A path for which
+// `stopAt` holds is returned at the point it is reached, because the filesystem is not asked about anything beyond it.
+export function followLinks(absolute: string, home: string, stopAt = (path: string) => isAppdata(path, home) || isSensitive(path)): string {
+  let path = "/";
+  let parts = absolute.split("/").filter(Boolean);
+  let followed = false;
+  let depth = 0;
+  while (parts.length) {
+    const part = parts.shift()!;
+    // The walk keeps the physical spelling, because `..` after the firmlink prefix leaves it, and only the check and the result use the plain one.
+    path = part === ".." ? dirname(firmlinks.has(path.toLowerCase()) ? unfirmlink(path) : path) : resolve(path, part);
+    if (stopAt(unfirmlink(path))) return unfirmlink(path);
+    let target: string;
+    try {
+      target = probes.readlink(path);
+    } catch (error) {
+      if (notALink.includes((error as NodeJS.ErrnoException).code ?? "")) continue;
+      throw error;
     }
-    return followed ? path : value;
-  };
-  const word = (w: Word, cwd: string): Word => {
-    if (w.expands || w.globs || !w.value || w.value.startsWith("-")) return w;
-    if (w.role === "program" && !w.value.includes("/")) return w;
-    if (!["arg", "path", "patfile", "option:patfile", "program"].includes(w.role)) return w;
-    const value = linked(w.value, cwd, /^['"]/.test(w.raw));
-    return value === w.value ? w : { ...w, value, text: w.role.startsWith("option:") ? w.text : value };
-  };
-  const commands = req.commands.map((cmd) => {
-    const checkedCwd = linked(cmd.cwd, "/");
-    const cwd = checkedCwd === cmd.cwd ? absPath(cmd.cwd, "/", req.home) : checkedCwd;
-    if (cwd !== cmd.cwd) changed = true;
-    return {
-      ...cmd,
-      cwd,
-      argv: cmd.argv.map((w, i) => (dataPrograms.has(basename(cmd.argv[cmd.program]?.text ?? "")) && i > cmd.program ? w : word(w, cmd.cwd))),
-      redirects: cmd.redirects.map((r) => ((r.direction === "in" || r.direction === "out") && r.target ? { ...r, target: linked(r.target, cmd.cwd) } : r)),
-    };
+    if (++depth > 8) throw new Error("Symlink chain exceeds the agent guard limit");
+    const targetPath = target.startsWith("/") ? target : `${dirname(path)}/${target}`;
+    followed = true;
+    parts = [...targetPath.split("/").filter(Boolean), ...parts];
+    path = "/";
+  }
+  return followed ? unfirmlink(path) : absolute;
+}
+
+// The path a glob target names up to its first wildcard segment: only that prefix exists as a path before the shell expands the rest.
+function followGlob(absolute: string, home: string): string {
+  const segments = absolute.split("/");
+  const wildcard = segments.findIndex((segment) => /[*?[{]/.test(segment));
+  if (wildcard < 0) return followLinks(absolute, home);
+  const prefix = segments.slice(0, wildcard).join("/") || "/";
+  const followed = followLinks(prefix, home);
+  return followed === prefix ? absolute : [followed === "/" ? "" : followed, ...segments.slice(wildcard)].join("/");
+}
+
+// Returns the same targets with followed paths replaced, or undefined when no path changed.
+export function linkedTargets(targets: Target[], home: string): Target[] | undefined {
+  let changed = false;
+  const result = targets.map((target) => {
+    if (target.expands || target.effect === "name" || (target.via === "tool" && target.glob)) return target;
+    const path = target.glob ? followGlob(target.unresolved, home) : followLinks(target.unresolved, home);
+    if (path === target.unresolved) return target;
+    changed = true;
+    return { ...target, path, unresolved: path };
   });
-  const checkedCwd = linked(req.inputCwd, "/");
-  const cwd = checkedCwd === req.inputCwd ? req.cwd : checkedCwd;
-  const target = req.target ? linked(req.pathInput, req.inputCwd) : req.target;
-  const searchRoot = req.searchRoot ? linked(req.pathInput || req.inputCwd, req.inputCwd) : req.searchRoot;
-  return changed ? { ...req, cwd, target, searchRoot, commands } : undefined;
+  return changed ? result : undefined;
 }

package/src/paths.ts

@@ -1,5 +1,4 @@
 // Filesystem checks run after lexical denials to avoid touching protected trees.
-import { realpathSync, statSync } from "node:fs";
 import { userInfo } from "node:os";
 import { basename, dirname, resolve } from "node:path";
 
@@ -17,6 +16,14 @@ export const sensitivePaths = [
   "**/auth.json*",
   "**/.credentials.json*",
   "**/.aws/credentials*",
+  "**/.netrc",
+  "**/.git-credentials",
+  "**/.docker/config.json",
+  "**/.kube/config",
+  "**/.pypirc",
+  "**/.pgpass",
+  "**/.cargo/credentials*",
+  "**/.config/gh/hosts.yml",
   "**/private-keys-v1.d",
   "**/private-keys-v1.d/**",
 ];
@@ -27,6 +34,11 @@ const sensitiveGlobs = sensitivePaths.map((path) => new Bun.Glob(path));
 // ~/.ssh has its own inode-based check and reason.
 const credentialRoots = [".aws", ".gnupg"];
 const credentialDirectories = [".ssh", ...credentialRoots];
+// The directory part of each listed file that sits in a named directory, such as .kube for .kube/config.
+const listedDirectories = sensitivePaths.flatMap((listed) => {
+  const tail = listed.replace(/^\*\*\//, "").split("/");
+  return tail.length > 1 && !tail.slice(0, -1).some((part) => part.includes("*")) ? [tail.slice(0, -1).join("/")] : [];
+});
 
 export function expandHome(path: string, home: string): string {
   for (const prefix of ["~", `~${userInfo().username}`]) {
@@ -35,10 +47,14 @@ export function expandHome(path: string, home: string): string {
   return path;
 }
 
+// /System/Volumes/Data is the same tree as the root through firmlinks, so a path spelled through it is judged as the plain path. Case is ignored
+// because the default APFS volume ignores it.
+export const unfirmlink = (path: string): string => path.replace(/^\/System\/Volumes\/Data(?=\/|$)/i, "") || "/";
+
 // curl, open and git read a file:// URL as the path it names.
 export function absPath(path: string, cwd: string, home: string, quoted = false): string {
   if (!quoted) path = expandHome(path, home);
-  return resolve(cwd, path.replace(/^file:\/\//i, ""));
+  return unfirmlink(resolve(cwd, path.replace(/^file:\/\//i, "")));
 }
 
 // Whether the shell could expand the glob's leading segments to `directory`, so
@@ -88,7 +104,7 @@ export function isLibrary(path: string, home: string): boolean {
   return path.toLowerCase() === `${home}/library`.toLowerCase() || isAppdata(path, home);
 }
 
-const sshPublic = (name: string) => /^(config|config\..*|.*\.pub|allowed_signers|known_hosts.*)$/s.test(name);
+export const sshPublic = (name: string) => /^(config|config\..*|.*\.pub|allowed_signers|known_hosts.*)$/s.test(name);
 
 // Under ~/.ssh only a top-level client config, public key, allowed_signers or
 // known_hosts file is public.
@@ -112,14 +128,66 @@ export function isSensitive(path: string, glob = false): boolean {
   if (!glob) return false;
   if (globDirectory(path)) return true;
   const base = basename(lower);
-  if (/^[*?]*$/.test(base)) return credentialDirectories.includes(basename(dirname(lower)));
-  const pattern = new Bun.Glob(base);
+  // A bare wildcard reaches every file in the directory, so a directory that holds a listed file counts.
+  if (/^[*?]*$/.test(base)) return credentialDirectories.includes(basename(dirname(lower))) || listedDirectories.some((dir) => dirname(lower).endsWith(`/${dir}`));
+  // A listed file inside a named directory needs the glob's directory to match too.
+  const segments = lower.split("/");
   return sensitivePaths.some((listed) => {
-    const name = basename(listed).replaceAll("*", "x");
-    return !/^x*$/.test(name) && pattern.match(name);
+    const tail = listed.replace(/^\*\*\//, "").split("/");
+    if (tail.length > segments.length) return false;
+    if (/^\**$/.test(tail.at(-1)!)) return false;
+    const names = tail.map((part) => part.replaceAll("*", "x"));
+    const offset = segments.length - tail.length;
+    if (!names.slice(0, -1).every((name, i) => new Bun.Glob(segments[offset + i]!).match(name))) return false;
+    // A named directory already narrows the match, so a glob that could reach any listed name in it counts.
+    return tail.length > 1 ? globsIntersect(segments.at(-1)!, tail.at(-1)!) : new Bun.Glob(segments.at(-1)!).match(names.at(-1)!);
   });
 }
 
+type GlobToken = "*" | ((char: string) => boolean);
+
+// Reads `*`, `?`, `[set]` and literal characters; a backslash escapes the next one.
+function globTokens(glob: string): GlobToken[] {
+  const tokens: GlobToken[] = [];
+  for (let i = 0; i < glob.length; i++) {
+    const char = glob[i]!;
+    const close = char === "[" ? glob.indexOf("]", i + 2) : -1;
+    if (char === "*") tokens.push("*");
+    else if (char === "?") tokens.push(() => true);
+    else if (close > 0) {
+      const matcher = new Bun.Glob(glob.slice(i, close + 1));
+      tokens.push((c) => matcher.match(c));
+      i = close;
+    } else {
+      const literal = char === "\\" ? (glob[++i] ?? char) : char;
+      tokens.push((c) => c === literal);
+    }
+  }
+  return tokens;
+}
+
+// Whether some file name matches both wildcard patterns.
+function globsIntersect(a: string, b: string): boolean {
+  const [left, right] = [globTokens(a), globTokens(b)];
+  const probes = Array.from({ length: 94 }, (_, i) => String.fromCharCode(33 + i));
+  const seen = new Set<string>();
+  const walk = (i: number, j: number): boolean => {
+    const key = `${i},${j}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    const [x, y] = [left[i], right[j]];
+    if (x === undefined && y === undefined) return true;
+    if (x === "*" && walk(i + 1, j)) return true;
+    if (y === "*" && walk(i, j + 1)) return true;
+    if (x === "*" && y === "*") return false;
+    if (x === "*") return y !== undefined && walk(i, j + 1);
+    if (y === "*") return x !== undefined && walk(i + 1, j);
+    if (x === undefined || y === undefined) return false;
+    return probes.some((c) => x(c) && y(c)) && walk(i + 1, j + 1);
+  };
+  return walk(0, 0);
+}
+
 // A wildcard directory segment such as `.s*` may expand to a credential
 // directory. The shell's wildcards skip a leading dot, so only a segment that
 // starts with one counts.
@@ -134,63 +202,14 @@ function globDirectory(path: string): boolean {
 
 // A search reads everything under its root, so a credential directory counts as
 // its listed files do.
-export function isSensitiveRoot(path: string): boolean {
-  return isSensitive(path) || credentialRoots.includes(basename(path.toLowerCase()));
-}
-
-// A path that does not exist or cannot be searched has no inode to compare.
-function stat(path: string) {
-  try {
-    return statSync(path);
-  } catch {
-    return undefined;
-  }
-}
-
-function sameFile(a: string, b: string): boolean {
-  if (a === b) return true;
-  const x = stat(a);
-  const y = stat(b);
-  return x !== undefined && y !== undefined && x.dev === y.dev && x.ino === y.ino;
-}
-
-function real(path: string): string {
-  try {
-    return realpathSync(path);
-  } catch {
-    return path;
-  }
-}
-
-function kind(path: string): "dir" | "file" | "other" {
-  const st = stat(path);
-  return st?.isDirectory() ? "dir" : st?.isFile() ? "file" : "other";
-}
-
-// Filesystem check for a file tool target, or a search root when search is
-// set. It follows symlinks and compares inodes so a link or a case alias of
-// ~/.ssh resolves to the directory it names.
-export function sshScopeDenied(target: string, home: string, search: boolean): boolean {
-  const ssh = `${home}/.ssh`;
-  const candidates = [...new Set([target, real(target)])];
-  const roots = [...new Set([ssh, real(ssh)])];
-  for (const candidate of candidates) {
-    for (const root of roots) {
-      if (sameFile(candidate, root)) return true;
-      if (search) {
-        for (let parent = root; parent !== "/";) {
-          parent = dirname(parent);
-          if (sameFile(candidate, parent)) return true;
-        }
-      }
-      for (let parent = candidate; parent !== "/";) {
-        parent = dirname(parent);
-        if (!sameFile(parent, root)) continue;
-        if (parent !== dirname(candidate) || !sshPublic(basename(candidate))) return true;
-        if (kind(target) === "dir") return true;
-        if (search && kind(target) !== "file") return true;
-      }
-    }
-  }
-  return false;
+export function isSensitiveRoot(path: string, home: string): boolean {
+  const lower = path.toLowerCase();
+  // A search from the home directory's .config reaches .config/gh because gh is not hidden.
+  const ancestors = listedDirectories.flatMap((dir) =>
+    dir
+      .split("/")
+      .slice(0, -1)
+      .map((_, i, parts) => `${home.toLowerCase()}/${parts.slice(0, i + 1).join("/")}`),
+  );
+  return isSensitive(path) || credentialRoots.includes(basename(lower)) || listedDirectories.some((dir) => lower.endsWith(`/${dir}`)) || ancestors.includes(lower);
 }

package/src/pipeline.ts

@@ -1,15 +1,80 @@
 import { basename } from "node:path";
 
-import type { Command } from "./record";
+import { stdinKind } from "./argv";
+import type { Command, Word } from "./record";
+import { showsHidden } from "./search-roles";
 
-// A literal printf value is known before xargs substitutes it into a command.
-export function xargsReplacements(left: Command[], right: Command[]): { source: string; cwd: string }[] {
-  const printf = left.find((cmd) => cmd.program >= 0 && basename(cmd.argv[cmd.program]!.text) === "printf");
-  const xargs = right.find((cmd) => cmd.program >= 0 && cmd.wrappers.includes("xargs"));
-  if (!printf || !xargs) return [];
-  const args = printf.argv.slice(printf.program + 1);
-  if (args.length !== 2 || !/^%s(?:\\n)?$/.test(args[0]!.text)) return [];
+// A dotfile name, or a glob the shell expands to dotfiles; `.` and `..` are directories.
+const hiddenName = (text: string) => /^\.(?!\.?$)/.test(basename(text));
+
+// xargs passes the names a walk printed to its command, so mark that command.
+export function markWalkedInput(left: Command[], right: Command[]) {
+  const walker = left.find((cmd) => {
+    const name = cmd.program >= 0 ? basename(cmd.argv[cmd.program]!.text) : "";
+    const args = cmd.argv.slice(cmd.program + 1);
+    const operands = args.filter((word) => !word.text.startsWith("-"));
+    if (name === "ls") return args.some((word) => /^(--all|--almost-all|-[A-Za-z0-9]*[aA][A-Za-z0-9]*)$/.test(word.text)) || operands.some((word) => hiddenName(word.text));
+    if (name === "echo" || name === "printf") return operands.some((word) => word.globs && hiddenName(word.text));
+    return name === "find" || (name === "fd" && showsHidden(args));
+  });
+  if (walker) for (const cmd of right) if (cmd.wrappers.includes("xargs")) cmd.items = { root: walker.cwd, hidden: true };
+}
 
+// printf and zsh's echo decode these escapes and stop at `\c`; a NUL separates xargs -0 items, so it reads as a line break.
+// A printf format takes up to three octal digits after the backslash; %b and echo take a leading 0 as well.
+const escapes: Record<string, string> = { n: "\n", t: "\t", "\\": "\\" };
+const unescape = (text: string, operand = false) =>
+  text
+    .split("\\c", 1)[0]!
+    .replace(
+      new RegExp(`\\\\(?:x([0-9a-fA-F]{1,2})|(${operand ? "0[0-7]{0,3}|[1-7][0-7]{0,2}" : "[0-7]{1,3}"})|([nt\\\\])|u([0-9a-fA-F]{1,4})|U([0-9a-fA-F]{1,8}))`, "g"),
+      (_, hex?: string, octal?: string, named?: string, unicode?: string, wide?: string) => {
+        const hexadecimal = hex ?? unicode ?? wide;
+        const code = hexadecimal !== undefined ? parseInt(hexadecimal, 16) : octal !== undefined ? parseInt(octal, 8) : undefined;
+        return code === undefined ? escapes[named!]! : code === 0 ? "\n" : String.fromCharCode(code);
+      },
+    );
+
+// What printf writes for a format built from literal text, %s, %b and %%; another conversion is unknown.
+function printfOutput(args: Word[]): string | undefined {
+  const [format, ...operands] = (args[0]?.text === "--" ? args.slice(1) : args).map((word) => word.text);
+  if (format === undefined) return "";
+  const pieces = format.split(/(%[sb%])/);
+  if (pieces.some((piece) => piece.includes("%") && !/^%[sb%]$/.test(piece))) return undefined;
+  const converts = pieces.some((piece) => /^%[sb]$/.test(piece));
+  let out = "";
+  do {
+    for (const piece of pieces) {
+      if (piece === "%%") out += "%";
+      else if (piece === "%s") out += operands.shift() ?? "";
+      else if (piece === "%b") out += unescape(operands.shift() ?? "", true);
+      else out += unescape(piece);
+    }
+  } while (converts && operands.length);
+  return out;
+}
+
+// A literal echo or printf value piped into a shell is the command line it runs.
+export function shellInput(left: Command[], right: Command[]): { source: string; cwd: string }[] {
+  const producer = left.find((cmd) => cmd.program >= 0 && ["printf", "echo"].includes(basename(cmd.argv[cmd.program]!.text)));
+  const shell = right.find((cmd) => cmd.program >= 0 && stdinKind(cmd) === "shell");
+  if (!producer || !shell) return [];
+  const args = producer.argv.slice(producer.program + 1);
+  const source =
+    basename(producer.argv[producer.program]!.text) === "printf"
+      ? printfOutput(args)
+      : unescape(
+          args
+            .filter((word) => !word.text.startsWith("-"))
+            .map((word) => word.text)
+            .join(" "),
+          true,
+        );
+  return source === undefined ? [] : [{ source, cwd: shell.cwd }];
+}
+
+// xargs runs its command once with every item, or once per item with -I.
+function xargsCommands(xargs: Command, items: string[]): { source: string; cwd: string }[] {
   const options = xargs.argv.slice(0, xargs.program);
   let marker = "";
   for (let i = 0; i < options.length; i++) {
@@ -18,11 +83,52 @@ export function xargsReplacements(left: Command[], right: Command[]): { source:
     else if (option.startsWith("-I")) marker = option.slice(2);
     else if (option.startsWith("--replace=")) marker = option.slice("--replace=".length);
   }
-  if (!marker) return [];
+  // xargs strips quotes and backslashes from what it reads, with or without -I.
+  const stripped = (value: string) => value.replace(/["'\\]/g, "");
   const quote = (value: string) => `'${value.replaceAll("'", "'\\''")}'`;
-  const source = xargs.argv
-    .slice(xargs.program)
-    .map((word) => (word.text.includes(marker) ? quote(word.text.replaceAll(marker, args[1]!.text)) : word.raw))
-    .join(" ");
-  return [{ source, cwd: xargs.cwd }];
+  const command = xargs.argv.slice(xargs.program);
+  // Without -I, xargs splits its input on blanks, so a printed line can become several arguments.
+  if (!marker)
+    return [
+      {
+        source: [
+          ...command.map((word) => word.raw),
+          ...items
+            .flatMap((item) => item.split(/\s+/))
+            .filter(Boolean)
+            .flatMap((item) => [item, stripped(item)])
+            .map(quote),
+        ].join(" "),
+        cwd: xargs.cwd,
+      },
+    ];
+  return items
+    .flatMap((line) => [line, stripped(line)])
+    .map((item) => ({ source: command.map((word) => (word.text.includes(marker) ? quote(word.text.replaceAll(marker, item)) : word.raw)).join(" "), cwd: xargs.cwd }));
+}
+
+// Literal printf and echo values are known before xargs passes them to a command.
+export function xargsReplacements(left: Command[], right: Command[]): { source: string; cwd: string }[] {
+  const producer = left.find((cmd) => cmd.program >= 0 && ["printf", "echo"].includes(basename(cmd.argv[cmd.program]!.text)));
+  const xargs = right.find((cmd) => cmd.program >= 0 && cmd.wrappers.includes("xargs"));
+  if (!producer || !xargs) return [];
+  const args = producer.argv.slice(producer.program + 1);
+  if (basename(producer.argv[producer.program]!.text) !== "printf")
+    return xargsCommands(
+      xargs,
+      args.filter((word) => !word.text.startsWith("-")).map((word) => unescape(word.text, true)),
+    );
+  const output = printfOutput(args);
+  return output === undefined ? [] : xargsCommands(xargs, output.split("\n").filter(Boolean));
+}
+
+// A here-string or here-document body is the item list xargs reads.
+export function xargsHereInput(xargs: Command, body: string): { source: string; cwd: string }[] {
+  return xargsCommands(
+    xargs,
+    body
+      .split("\n")
+      .flatMap((line) => line.split(/\s+/))
+      .filter(Boolean),
+  );
 }

package/src/probes.ts

@@ -0,0 +1,5 @@
+// The only filesystem calls the guard makes about a path taken from a command. Tests replace these to record each probed path and check that
+// none of them resolves into App Data, so every caller must reach the filesystem through here.
+import { readlinkSync, statSync } from "node:fs";
+
+export const probes = { readlink: readlinkSync, stat: statSync };