@loophubs/agent-guard 0.3.0 → 0.4.0

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";
 
@@ -48,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
@@ -101,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.
@@ -210,60 +213,3 @@ export function isSensitiveRoot(path: string, home: string): boolean {
   );
   return isSensitive(path) || credentialRoots.includes(basename(lower)) || listedDirectories.some((dir) => lower.endsWith(`/${dir}`)) || ancestors.includes(lower);
 }
-
-// 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;
-}

package/src/pipeline.ts

@@ -2,18 +2,14 @@ import { basename } from "node:path";
 
 import { stdinKind } from "./argv";
 import type { Command, Word } from "./record";
-
-// fd and ls skip hidden files unless asked; find never does.
-export function showsHidden(words: Word[]): boolean {
-  return words.some((word) => /^(--hidden|--unrestricted)$/.test(word.text) || /^-[A-Za-z]*[Hu][A-Za-z]*$/.test(word.text));
-}
+import { showsHidden } from "./search-roles";
 
 // 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 walks = left.some((cmd) => {
+  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("-"));
@@ -21,7 +17,7 @@ export function markWalkedInput(left: Command[], right: Command[]) {
     if (name === "echo" || name === "printf") return operands.some((word) => word.globs && hiddenName(word.text));
     return name === "find" || (name === "fd" && showsHidden(args));
   });
-  if (walks) for (const cmd of right) if (cmd.wrappers.includes("xargs")) cmd.flags.add("walked");
+  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.

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 };

package/src/programs.ts

@@ -0,0 +1,341 @@
+// How each program obtains the paths it touches and what it does with them.
+// A program with no entry reads every path it is handed.
+import { dockerTargets } from "./docker-targets";
+import { gitTargets } from "./git-targets";
+import type { Command, Effect, Target, Word } from "./record";
+import { searchTargets } from "./search-targets";
+import { sshTargets } from "./ssh-targets";
+
+type Walk = Target["walk"];
+
+interface Make {
+  via?: Target["via"];
+  base?: string | undefined;
+  glob?: boolean;
+  sends?: boolean;
+  walk?: Walk;
+  search?: boolean;
+  quoted?: boolean; // the path is literal: no ~ expansion
+}
+
+export interface Context {
+  cmd: Command;
+  words: Word[];
+  walk: Walk;
+  claimed: Set<Word>;
+  make: (path: string, word: Word | undefined, effect: Effect, options?: Make) => Target;
+}
+
+export interface ProgramSpec {
+  operands?: Effect; // default "read": a program the table does not model reads every path it is handed
+  walk?: Walk | { recursive: RegExp }; // default "visible"; { recursive } is "visible" only when an option matches
+  options?: Record<string, Effect>; // effect of an option's value, glued with = or separate
+  last?: Effect; // the final operand
+  sends?: boolean; // reads leave the machine
+  remote?: RegExp; // an operand on another machine is a name; with `sends`, reads leave only when an operand is remote
+  cwd?: "cwd" | "scan"; // a command with no path operand lists its working directory
+  targets?: (ctx: Context) => Target[];
+}
+
+export const DEFAULT_EFFECT: Effect = "read";
+
+// Programs that read only the paths they are handed, so a command that names another directory does not read the working directory.
+export const readers = (
+  "cat head tail less more bat sed awk jq yq base64 xxd od strings diff openssl plutil cp tee tar source . sort " +
+  "uniq cut nl fold rev paste comm join iconv hexdump hd zcat gzcat bzcat xzcat ag ack tac column pr vim vi nvim view perl ruby dd scp rsync zip ed ex hg svn sh bash zsh dash ksh wget php zgrep zless zmore"
+).split(" ");
+export const dataPrograms = "echo printf print : true false export set unset typeset declare local".split(" ");
+// Metadata, counts and digests: no content reaches the output.
+const meta = "stat test [ chmod chown chgrp chflags touch rm rmdir mkdir mv ln wc file shasum sha1sum sha256sum md5 md5sum cksum realpath readlink basename dirname".split(" ");
+const noWalk = new Set("stat test [ mkdir mv".split(" "));
+
+// The value of these options is consumed by the program, not read into the output.
+const intoDirectory: Record<string, Effect> = { "-t": "write", "--target-directory": "write" };
+export const globalOptions: Record<string, Effect> = { "--exclude": "name", "--exclude-dir": "name", "--include": "name" };
+
+const remote = /^(rsync:\/\/|([^/@:]+@)?[^/@:]+:)/;
+const lsRecursive = /^(--recursive$|-[^-]*R)/;
+const anyRecursive = /^(--recursive$|-[^-]*[rR])/;
+
+// curl's short options that take a value; the rest of a cluster is that value.
+export const curlValueLetters = "AbcCdDeEFHKmoPQrTtuUwxXyYz";
+const curlDataOptions = /^(d|data|data-ascii|data-binary|data-urlencode|json|H|header|proxy-header|url-query|variable)$/;
+
+// The options whose value is a file curl writes; `-` sends the output to standard output.
+const curlWrites = ["o", "output", "D", "dump-header", "c", "cookie-jar", "etag-save", "libcurl", "stderr", "hsts", "alt-svc", "trace", "trace-ascii", "ssl-sessions"];
+
+function curlTargets({ words, make, claimed }: Context): Target[] {
+  const targets: Target[] = [];
+  // The text after an @ or < inside a value is literal: neither the shell nor curl expands a ~ there.
+  const read = (path: string, word: Word, quoted?: boolean, sends = true) => {
+    claimed.add(word);
+    targets.push(make(path, word, "read", { via: "option", sends, ...(quoted && { quoted }) }));
+  };
+  // -O and --remote-name save each download under its remote name, in the working directory or the --output-dir.
+  let remoteName = false;
+  let outputDir: Word | undefined;
+  for (let i = 0; i < words.length; i++) {
+    const word = words[i]!;
+    const text = word.text;
+    if (text === "--") break;
+    remoteName ||= /^(--remote-name(-all)?|-[^-]*O)$/.test(text);
+    if (/^--output-dir(=|$)/.test(text)) {
+      outputDir = text.includes("=") ? word : words[++i];
+      if (outputDir) claimed.add(outputDir);
+      continue;
+    }
+    // curl reads `file:path` and `file://path` alike, decodes %XX, and expands `[a-z]` and `{a,b}` ranges.
+    const url = /^(--url=)?(file:.*)$/is.exec(text);
+    if (url) {
+      claimed.add(word);
+      const path = url[2]!.replace(/^file:(\/\/)?/i, "").replace(/%([0-9a-f]{2})/gi, (_, hex: string) => String.fromCharCode(parseInt(hex, 16)));
+      targets.push(make(path, word, "read", { via: "operand", glob: /[[{]/.test(path) }));
+      continue;
+    }
+    let key = "";
+    let value = "";
+    const long =
+      /^--(data|data-ascii|data-binary|data-urlencode|json|form|header|proxy-header|url-query|variable|upload-file|config|output|dump-header|write-out|cookie|etag-compare|cookie-jar|etag-save|libcurl|stderr|hsts|alt-svc|trace|trace-ascii|ssl-sessions)(=|$)/s.exec(
+        text,
+      );
+    if (long) {
+      key = long[1]!;
+      value = text.includes("=") ? text.slice(text.indexOf("=") + 1) : (words[++i]?.text ?? "");
+    } else if (/^-[^-]/.test(text)) {
+      for (let k = 1; k < text.length; k++) {
+        if (!curlValueLetters.includes(text[k]!)) continue;
+        key = text[k]!;
+        value = text.slice(k + 1) || (words[++i]?.text ?? "");
+        break;
+      }
+    }
+    const from = words[i]!;
+    if (curlDataOptions.test(key)) {
+      if (/@./s.test(value)) read(value.slice(value.indexOf("@") + 1), from, true);
+    } else if (key === "F" || key === "form") {
+      const file = value.slice(value.indexOf("=") + 1).replace(/^[@<]/, "");
+      // A quoted file name may hold a `;`.
+      read(/^"([^"]*)"/.exec(file)?.[1] ?? file.split(";")[0]!, from, true);
+    } else if (["T", "upload-file", "K", "config", "etag-compare"].includes(key)) read(value, from);
+    // The response is written out with the text of a `@file` template; `@-` is standard input.
+    else if ((key === "w" || key === "write-out") && /^@./.test(value) && value !== "@-") read(value.slice(1), from, true, false);
+    // A cookie value with no `=` names a cookie file that curl parses itself.
+    else if ((key === "b" || key === "cookie") && value && !value.includes("=")) {
+      claimed.add(from);
+      targets.push(make(value, from, "use", { via: "option" }));
+    } else if (curlWrites.includes(key) && value) {
+      claimed.add(from);
+      // `-o -` sends the response to standard output, so it names no file.
+      if (value !== "-") targets.push(make(value, from, "write", { via: "option" }));
+    }
+  }
+  if (remoteName) targets.push(make(outputDir ? outputDir.text.replace(/^--output-dir=/, "") : ".", outputDir, "write", { via: "option", walk: "none" }));
+  return targets;
+}
+
+function ddTargets({ words, make, claimed }: Context): Target[] {
+  const targets: Target[] = [];
+  for (const word of words) {
+    claimed.add(word);
+    if (word.text.startsWith("if=")) targets.push(make(word.text.slice(3), word, "read", { via: "option" }));
+    else if (word.text.startsWith("of=")) targets.push(make(word.text.slice(3), word, "write", { via: "option" }));
+  }
+  return targets;
+}
+
+// A cluster of tar's short options, such as `-czf`, or the first word without a dash.
+const tarCluster = (word: Word, i: number) => !word.text.startsWith("--") && (word.text.startsWith("-") || i === 0);
+
+// The archive is the value of -f or --file: the rest of a cluster such as `-cfout.tar`, or the next word.
+function tarArchive(words: Word[]): { word: Word; path: string } | undefined {
+  for (const [i, word] of words.entries()) {
+    const text = word.text;
+    if (text.startsWith("--file=")) return { word, path: text.slice("--file=".length) };
+    const next = words[i + 1];
+    if (text === "--file" && next) return { word: next, path: next.text };
+    const cluster = tarCluster(word, i) ? /^-?[^Cf]*f(.*)$/s.exec(text) : null;
+    if (cluster?.[1]) return { word, path: cluster[1] };
+    if (cluster && next) return { word: next, path: next.text };
+  }
+  return undefined;
+}
+
+// A directory given to -C is entered, and later operands are relative to it.
+function tarTargets({ words, make, claimed }: Context): Target[] {
+  const targets: Target[] = [];
+  let base: string | undefined;
+  const creates = words.some((word, i) => word.text === "--create" || (tarCluster(word, i) && /^-?[^CfT]*c/.test(word.text)));
+  // Extraction writes into the directory -C names, so the directory is judged as a write.
+  const extracts = words.some((word, i) => /^--(extract|get)$/.test(word.text) || (tarCluster(word, i) && /^-?[^CfT]*x/.test(word.text)));
+  const archive = tarArchive(words);
+  if (archive) {
+    claimed.add(archive.word);
+    targets.push(make(archive.path, archive.word, creates ? "write" : "read", { via: "option" }));
+  }
+  for (const [i, word] of words.entries()) {
+    const text = word.text;
+    if (word === archive?.word) continue;
+    if (/^--exclude=/.test(text)) {
+      claimed.add(word);
+      continue;
+    }
+    // The directory is the word after -C, --directory or --cd, or the value glued to them, as in `-C/dir` and `-xC/dir`.
+    const glued = /^(?:--directory=|-[^-]*C)(.+)$/s.exec(text)?.[1];
+    const enters = glued !== undefined || /^(--directory|--cd|-[^-]*C)$/.test(words[i - 1]?.text ?? "");
+    if (!enters) {
+      if (base !== undefined && !text.startsWith("-")) {
+        claimed.add(word);
+        targets.push(make(text, word, "read", { via: "operand", base }));
+      }
+      continue;
+    }
+    claimed.add(word);
+    const dir = glued ?? text;
+    const target = make(dir, word, extracts ? "write" : "enter", { via: "option", base });
+    targets.push(target);
+    base = target.path;
+  }
+  // Without -C the members land in the working directory, unless -O sends them to stdout.
+  const toStdout = words.some((word, i) => word.text === "--to-stdout" || (tarCluster(word, i) && /^-?[^CfT]*O/.test(word.text)));
+  if (extracts && base === undefined && !toStdout) targets.push(make(".", undefined, "write", { via: "option", walk: "none" }));
+  return targets;
+}
+
+const wgetShort: Record<string, string> = { i: "input-file", O: "output-document", e: "execute", P: "directory-prefix", o: "output-file", a: "append-output" };
+// The options whose value is written: the download, the log, or the directory the downloads go to.
+const wgetWrites = ["output-document", "output-file", "append-output", "directory-prefix", "save-cookies", "warc-file", "hsts-file"];
+// wgetrc command names ignore case, underscores and hyphens.
+const wgetrc: Record<string, string> = {
+  postfile: "post-file",
+  bodyfile: "body-file",
+  input: "input-file",
+  outputdocument: "output-document",
+  logfile: "output-file",
+  dirprefix: "directory-prefix",
+  loadcookies: "load-cookies",
+  savecookies: "save-cookies",
+  warcfile: "warc-file",
+  hstsfile: "hsts-file",
+};
+
+// The file that holds the request body leaves the machine, as can a wgetrc file that names one, and the output document is written; `-e` runs a wgetrc command that can name either.
+function wgetTargets({ words, make, claimed }: Context): Target[] {
+  const targets: Target[] = [];
+  // A download lands in the working directory unless -O or a directory prefix says otherwise.
+  let placed = false;
+  for (const [i, word] of words.entries()) {
+    const text = word.text;
+    if (text === "--spider") placed = true;
+    const long = /^--(post-file|body-file|input-file|output-document|output-file|append-output|directory-prefix|save-cookies|warc-file|hsts-file|execute|config|load-cookies)(=|$)/.exec(text);
+    // The value is glued to the flag (-i.env) or follows it.
+    const short = /^-[A-Za-z]*?([ieOPoa])(.*)$/.exec(text);
+    let key = long?.[1] ?? wgetShort[short?.[1] ?? ""];
+    if (!key) continue;
+    const glued = long ? text.includes("=") : !!short?.[2];
+    const value = glued ? word : words[i + 1];
+    if (!value) continue;
+    let path = !glued ? value.text : long ? text.slice(text.indexOf("=") + 1) : short![2]!;
+    if (key === "execute") {
+      const command = /^\s*([A-Za-z_-]+)\s*=\s*(.*)$/.exec(path);
+      const name = wgetrc[command?.[1]!.toLowerCase().replace(/[_-]/g, "") ?? ""];
+      if (!command || !name) continue;
+      key = name;
+      path = command[2]!;
+    }
+    claimed.add(value);
+    placed ||= key === "output-document" || key === "directory-prefix";
+    // `-O -` writes the document to standard output, so it names no file.
+    if (key === "output-document" && path === "-") continue;
+    targets.push(make(path, value, wgetWrites.includes(key) ? "write" : "read", { via: "option", walk: "none", sends: ["post-file", "body-file", "config"].includes(key) }));
+  }
+  if (!placed) targets.push(make(".", undefined, "write", { via: "option", walk: "none" }));
+  return targets;
+}
+
+const findExpression = /^(-|\(|!)/;
+const findExec = ["-exec", "-execdir", "-ok", "-okdir"];
+
+// The paths before find's first expression word, including the one `-f` names.
+export function findRoots(words: Word[]): Word[] {
+  const roots: Word[] = [];
+  let i = 0;
+  while (words[i]) {
+    if (words[i]!.text === "-f" && words[i + 1]) roots.push(words[(i += 2) - 1]!);
+    else if (words[i]!.text === "--" || /^-[HLPEXxdsO]/.test(words[i]!.text)) i++;
+    else break;
+  }
+  for (; words[i] && !findExpression.test(words[i]!.text); i++) roots.push(words[i]!);
+  return roots;
+}
+
+function findTargets({ words, make, claimed }: Context): Target[] {
+  const targets: Target[] = [];
+  for (const root of findRoots(words)) {
+    claimed.add(root);
+    targets.push(make(root.text, root, "list", { via: "operand", walk: "hidden" }));
+  }
+  for (const word of words) if (!findExec.includes(word.text)) claimed.add(word);
+  return targets;
+}
+
+// The first operand is the filter, unless -f names a file that holds it; yq names its evaluation command before the filter.
+const filterTargets =
+  (commands: string[]) =>
+  ({ words, claimed }: Context): Target[] => {
+    const operands = words.filter((word) => !word.text.startsWith("-"));
+    const filter = words.some((word) => word.text === "-f" || word.text === "--from-file") ? undefined : operands[commands.includes(operands[0]?.text ?? "") ? 1 : 0];
+    if (filter) claimed.add(filter);
+    return [];
+  };
+
+export const specs = new Map<string, ProgramSpec>();
+for (const name of readers) specs.set(name, {});
+for (const name of dataPrograms) specs.set(name, { operands: "name", walk: "none" });
+for (const name of meta) specs.set(name, { operands: "meta", ...(noWalk.has(name) && { walk: "none" as const }) });
+for (const name of ["cd", "pushd", "popd"]) specs.set(name, { operands: "enter", walk: "none" });
+specs.set("jq", { targets: filterTargets([]) });
+specs.set("yq", { targets: filterTargets(["eval", "e", "eval-all", "ea"]) });
+specs.set("gh", {});
+specs.set("ls", { operands: "list", walk: { recursive: lsRecursive }, cwd: "cwd" });
+specs.set("tree", { operands: "list", cwd: "scan" });
+specs.set("du", { operands: "list", cwd: "scan" });
+specs.set("cp", { options: intoDirectory, last: "write", walk: { recursive: anyRecursive } });
+specs.set("dd", { walk: "none", targets: ddTargets });
+specs.set("tar", { targets: tarTargets });
+specs.set("tee", { operands: "write" });
+specs.set("install", { options: intoDirectory, last: "write" });
+specs.set("scp", { last: "write", sends: true, remote, targets: sshTargets("scp") });
+specs.set("sftp", { targets: sshTargets("sftp") });
+specs.set("rsync", { options: { "--files-from": "read", "--exclude-from": "read", "--include-from": "read" }, last: "write", sends: true, remote });
+specs.set("wget", {
+  operands: "name",
+  options: { "--ca-certificate": "use", "--ca-directory": "use", "--certificate": "use", "--private-key": "use", "--crl-file": "use", "--random-file": "use" },
+  targets: wgetTargets,
+});
+// The value of these options is a certificate, key or list file that curl uses itself.
+const curlUsedFiles =
+  "--cacert --capath --cert --key -E --netrc-file --crlfile --egd-file --knownhosts --proxy-cacert --proxy-capath --proxy-cert --proxy-crlfile --proxy-key --random-file --pubkey --pinnedpubkey --proxy-pinnedpubkey --unix-socket";
+specs.set("curl", { operands: "name", options: Object.fromEntries(curlUsedFiles.split(" ").map((option) => [option, "use" as const])), targets: curlTargets });
+specs.set("git", { targets: gitTargets });
+specs.set("docker", { operands: "name", options: { "--env-file": "use" }, targets: dockerTargets });
+for (const name of ["node", "bun", "deno"]) specs.set(name, { options: { "--env-file": "use" } });
+specs.set("kubectl", { options: { "--kubeconfig": "use" } });
+specs.set("ssh", { operands: "name", targets: sshTargets("ssh") });
+specs.set("ssh-add", { operands: "use" });
+specs.set("ssh-keygen", { options: { "-f": "use" } });
+specs.set("dotenvx", { options: { "-f": "use", "--file": "use", "--env-file": "use" } });
+for (const name of ["npm", "pnpm", "yarn"]) specs.set(name, { options: { "--userconfig": "use" } });
+for (const name of ["rg", "grep", "ag", "ack"]) specs.set(name, { targets: (ctx) => searchTargets(name, ctx) });
+specs.set("find", { operands: "list", cwd: "scan", targets: findTargets });
+specs.set("fd", { operands: "list", cwd: "scan" });
+
+export function specFor(name: string): ProgramSpec {
+  return specs.get(name) ?? {};
+}
+
+export function walkOf(spec: ProgramSpec, name: string, words: Word[]): Walk {
+  const { walk } = spec;
+  if (typeof walk === "object") return words.some((word) => walk.recursive.test(word.text)) ? "visible" : "none";
+  if (name === "git" && words.some((word) => word.text === "config")) return "none";
+  return walk ?? "visible";
+}

package/src/reasons.ts

@@ -3,7 +3,9 @@ export const reasons = {
   appdata:
     "This reads a protected macOS app-data directory. Name a specific non-sensitive file under ~/Library/Application Support instead, or ask the user to inspect the protected file and share the needed fact.",
   broad: "A scan rooted at the home directory or ~/Library reaches every app-data entry. Scope the scan to a project path.",
-  file: "This reads a credential or environment file. Read a non-sensitive config file instead; if a fact from this file is needed, ask the user to inspect it and share only that fact.",
+  file: "This reads a credential or environment file. If a client the guard models only needs to use the file, pass it through that program's own option, such as `--env-file`, `--kubeconfig`, or `ssh -i`; the guard does not control what the client does with the contents. Otherwise read a non-sensitive config file, or ask the user to inspect the file and share only the fact needed.",
+  codeFile:
+    "This inline code names a credential or environment file. To write text that mentions the file, use the Write or Edit tool; to run code that needs its values, pass the file through a modelled runtime's option, such as `node --env-file=.env`, though the guard does not control what the runtime does with the contents; otherwise ask the user to inspect the file and share only the fact needed.",
   hiddenSearch: "A recursive search that includes hidden files can read credentials. Use default rg on a project path, or search an exact non-sensitive file without recursive or hidden-file flags.",
   dump: "This dumps environment or shell variables, including secrets. Name the non-sensitive variable needed and read only that variable.",
   variable: "This prints the value of a credential variable. Ask the user for the specific non-sensitive fact needed, or let the authorized client consume the credential without printing it.",

package/src/record.ts

@@ -1,7 +1,7 @@
 // A search option's value keeps the option's word as option:ROLE.
 export type ValueRole = "pattern" | "patfile" | "glob" | "nglob" | "optarg";
 export type Role = "arg" | "assign" | "precommand" | "namespace" | "program" | "code" | "option" | "path" | ValueRole | `option:${ValueRole}`;
-export type Flag = "explicit" | "files" | "help" | "fixed" | "recursive" | "include" | "replace" | "hidden" | "walked";
+export type Flag = "explicit" | "files" | "help" | "fixed" | "recursive" | "include" | "replace" | "hidden";
 
 export interface Word {
   text: string; // quotes removed; ~, $HOME and ${HOME} expanded
@@ -21,6 +21,28 @@ export interface Redirect {
   vars: string[]; // parameters the shell expands in the target or body
 }
 
+export type Effect = "read" | "write" | "list" | "meta" | "use" | "enter" | "name";
+
+// The file names a walk hands to a command through find -exec, fd -x or xargs.
+export interface Items {
+  root: string;
+  hidden: boolean;
+}
+
+// A path a command touches, with what the command does to it.
+export interface Target {
+  path: string; // absolute; ~, $HOME and $PWD expanded when unquoted, resolved against the command's cwd or a tar -C base
+  unresolved: string; // the same path before `..` is folded, for the symlink walk
+  glob: boolean; // the shell expands it before the program runs
+  effect: Effect;
+  walk: "none" | "visible" | "hidden"; // a read or list of a directory reaches what is under it; hidden includes dotfiles
+  sends: boolean; // the program transmits what it reads
+  expands: boolean; // the word held an expansion the front end could not resolve
+  via: "tool" | "operand" | "option" | "redirect" | "items" | "cwd" | "scan" | "code";
+  search: boolean; // root of a content search
+  command: number; // index of the command in Request.commands, -1 for a tool request
+}
+
 export interface Command {
   argv: Word[];
   redirects: Redirect[];
@@ -29,11 +51,18 @@ export interface Command {
   wrappers: string[];
   shell: boolean; // the program runs in this shell rather than behind a wrapper
   flags: Set<Flag>;
+  items?: Items;
+}
+
+// Text the front end cannot structure into commands, such as the code an interpreter runs.
+export interface Fragment {
+  text: string;
+  cwd: string;
 }
 
 export interface Script {
   commands: Command[];
-  uninspectable: string[];
+  uninspectable: Fragment[];
   parseFailed: boolean;
 }
 
@@ -52,6 +81,6 @@ export interface Request {
   searchRoot: string;
   glob: string;
   commands: Command[];
-  uninspectable: string[];
+  uninspectable: Fragment[];
   parseFailed: boolean;
 }