@loophubs/agent-guard 0.3.0 → 0.4.0

package/src/search-targets.ts

@@ -0,0 +1,33 @@
+import { basename } from "node:path";
+
+import type { Context } from "./programs";
+import type { Effect, Target } from "./record";
+
+// rg, grep, ag and ack: the roles search-roles.ts gave the words say which are roots, pattern files and globs.
+export function searchTargets(name: string, { cmd, words, make, claimed }: Context): Target[] {
+  const help = cmd.flags.has("help");
+  const files = cmd.flags.has("files");
+  const recursive = name === "grep" && cmd.flags.has("recursive");
+  const walk = recursive || (["rg", "ag"].includes(name) && cmd.flags.has("hidden")) ? "hidden" : "visible";
+  // Listing names, or printing help, reads no content; a hidden listing feeds what reads it.
+  const effect: Effect = help || (files && walk !== "hidden") ? "list" : "read";
+  const targets: Target[] = [];
+  for (const [i, word] of words.entries()) {
+    // The file these options name holds ignore rules that the search reads.
+    const owner = word.role === "optarg" ? words[i - 1] : word.role === "option:optarg" ? word : undefined;
+    if (word.role === "path") targets.push(make(word.value, word, effect, { via: "operand", walk }));
+    else if (word.role === "patfile" || word.role === "option:patfile") targets.push(make(word.value, word, effect, { via: "option", walk: "none" }));
+    else if (owner && /^--(ignore-file|exclude-from)(=|$)/.test(owner.text)) targets.push(make(word.value, word, "read", { via: "option", walk: "none" }));
+    else continue;
+    claimed.add(word);
+  }
+  const scoped = targets.some((target) => target.via === "operand");
+  if (!scoped && (name !== "grep" || recursive)) targets.push(make(cmd.cwd, undefined, help ? "list" : effect, { via: name === "grep" ? "cwd" : "scan", walk, search: !help }));
+  for (const word of words) {
+    if (word.role !== "glob" && word.role !== "option:glob") continue;
+    claimed.add(word);
+    // A positive glob selects files even past ignore rules.
+    targets.push(make(basename(word.value), word, effect, { via: "option", glob: true, walk: "none" }));
+  }
+  return targets;
+}

package/src/ssh-targets.ts

@@ -0,0 +1,46 @@
+import type { Context } from "./programs";
+import type { Effect, Target } from "./record";
+
+// `-o KEY=VALUE`, `-o "KEY VALUE"` and `-oKEY=VALUE` set a client option; these keys name a file the client reads or writes.
+const sshFileOptions: Record<string, Effect> = { identityfile: "use", certificatefile: "use", globalknownhostsfile: "use", userknownhostsfile: "write", revokedhostkeys: "use", pkcs11provider: "use" };
+
+// The option letters that take a value, from each client's synopsis in the OpenSSH 10.3p1 manual page; the first one in a cluster takes the rest of the word or the next word.
+const valueLetters: Record<string, string> = { ssh: "BDEFIJLOPQRSWbceilmopw", scp: "DFJPSXcilo", sftp: "BDFJPRSXbcilos" };
+
+// The client uses the identity and configuration files itself (sftp passes them to ssh), and ssh writes its log file.
+const letterEffects: Record<string, Effect> = { i: "use", F: "use", E: "write" };
+
+// ssh reads options before and right after the destination, scp and sftp before their first operand; later words are the remote command or operands.
+export const sshTargets =
+  (client: "ssh" | "scp" | "sftp") =>
+  ({ words, make, claimed }: Context): Target[] => {
+    const targets: Target[] = [];
+    let operands = 0;
+    for (let i = 0; i < words.length; i++) {
+      const word = words[i]!;
+      if (word.text === "--") break;
+      if (!/^-./.test(word.text)) {
+        if (++operands === (client === "ssh" ? 2 : 1)) break;
+        continue;
+      }
+      const at = [...word.text.slice(1)].findIndex((letter) => valueLetters[client]!.includes(letter));
+      if (at < 0) continue;
+      const letter = word.text[at + 1]!;
+      const glued = word.text.slice(at + 2);
+      const holder = glued ? word : words[++i];
+      if (!holder) break;
+      const value = glued || holder.text;
+      let effect: Effect | undefined = client === "sftp" && letter === "b" && value !== "-" ? "read" : letterEffects[letter];
+      let paths = [value];
+      if (letter === "o") {
+        const setting = /^(\w+)(?:\s*=\s*|\s+)(.+)$/s.exec(value);
+        effect = sshFileOptions[setting?.[1]?.toLowerCase() ?? ""];
+        // ssh strips double quotes, takes several known-hosts files separated by spaces, and expands %d and ${HOME} to the home directory.
+        paths = (setting?.[2] ?? "").match(/"[^"]*"|\S+/g)?.map((path) => path.replace(/"/g, "").replace(/^(%d|\$\{HOME\})(?=\/|$)/, "~")) ?? [];
+      }
+      if (!effect) continue;
+      claimed.add(holder);
+      for (const path of paths) targets.push(make(path, holder, effect, { via: "option", ...(letter === "o" && { quoted: false }) }));
+    }
+    return targets;
+  };

package/src/ssh.ts

@@ -0,0 +1,65 @@
+import { basename, dirname } from "node:path";
+
+import { followLinks, notALink } from "./links";
+import { isAppdata, sshPublic } from "./paths";
+import { probes } from "./probes";
+
+// A path that does not exist has no inode to compare. Any other failure means the comparison did not run, so it propagates.
+function stat(path: string) {
+  try {
+    return probes.stat(path);
+  } catch (error) {
+    if (notALink.includes((error as NodeJS.ErrnoException).code ?? "")) return undefined;
+    throw error;
+  }
+}
+
+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 kind(path: string): "dir" | "file" | "other" {
+  const st = stat(path);
+  return st?.isDirectory() ? "dir" : st?.isFile() ? "file" : "other";
+}
+
+// Whether the spelling puts a path at or under `root`, or for a search above it. Case is ignored because the default APFS volume ignores it.
+function near(path: string, root: string, search: boolean): boolean {
+  const [spelled, base] = [path.toLowerCase().replace(/\/$/, "") || "/", root.toLowerCase()];
+  return spelled === base || spelled.startsWith(`${base}/`) || (search && (spelled === "/" || base.startsWith(`${spelled}/`)));
+}
+
+// Filesystem check for a file tool target, or a search root when search is set. It compares inodes so a case alias of ~/.ssh resolves to the
+// directory it names. Only a path whose spelling, or whose readlink-followed spelling, is already at or under ~/.ssh is compared: the inode
+// probes follow links, so a target that is not established to be in ~/.ssh scope is never handed to them. When ~/.ssh scope leads into App Data
+// the comparison is skipped and the target is denied, because stat would search that tree.
+export function sshScopeDenied(target: string, home: string, search: boolean): boolean {
+  const ssh = `${home}/.ssh`;
+  const appdataOnly = (path: string) => isAppdata(path, home);
+  const roots = [...new Set([ssh, followLinks(ssh, home, appdataOnly)])];
+  const candidates = [...new Set([target, followLinks(target, home, appdataOnly)])];
+  if (!candidates.some((candidate) => roots.some((root) => near(candidate, root, search)))) return false;
+  if ([...roots, ...candidates].some((path) => isAppdata(path, home))) return true;
+  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/targets.ts

@@ -0,0 +1,151 @@
+// Turn a request into inferred targets under modelled command semantics, each with what the command is modelled to do to it.
+import { basename } from "node:path";
+
+import { programName } from "./argv";
+import { absPath, expandHome } from "./paths";
+import { type Context, DEFAULT_EFFECT, dataPrograms, globalOptions, specFor, specs, walkOf } from "./programs";
+import type { Command, Effect, Request, Target, Word } from "./record";
+
+const pathRoles = new Set(["arg", "path", "patfile", "option:patfile", "optarg"]);
+
+function maker(home: string, cmd: Command, command: number, walk: Target["walk"], sends: boolean): Context["make"] {
+  return (path, word, effect, options = {}) => {
+    const quoted = options.quoted ?? (word ? /^['"]/.test(word.raw) : false);
+    const input = (quoted ? path : expandHome(path, home)).replace(/^file:\/\//i, "");
+    const base = options.base ?? cmd.cwd;
+    return {
+      path: absPath(path, base, home, quoted),
+      unresolved: input.startsWith("/") ? input : `${base}/${input}`,
+      glob: options.glob ?? word?.globs ?? false,
+      effect,
+      walk: options.walk ?? walk,
+      sends: options.sends ?? sends,
+      expands: word?.expands ?? false,
+      via: options.via ?? "operand",
+      search: options.search ?? false,
+      command,
+    };
+  };
+}
+
+// A glued `--name=value` is a path in the value, and `@path` or an httpie `field=@path` reads the file; a bare option is not a path.
+function operandValue(word: Word): string | undefined {
+  const value = word.value.startsWith("-") ? (word.value.includes("=") ? word.value.slice(word.value.indexOf("=") + 1) : undefined) : word.value;
+  if (value === undefined) return undefined;
+  if (value.startsWith("@")) return value.slice(1) || undefined;
+  return /^[^=@\s]+?(?:==?|:)@(.+)$/s.exec(value)?.[1] ?? value;
+}
+
+function commandTargets(cmd: Command, command: number, home: string): Target[] {
+  const program = cmd.argv[cmd.program];
+  const name = program ? programName(program.text) : "";
+  const spec = specFor(name);
+  // A command with no program, such as a for loop's word list, still names paths.
+  const words = cmd.argv.slice(cmd.program + 1);
+  const walk = walkOf(spec, name, words);
+  const options = { ...globalOptions, ...spec.options };
+  // An option's value takes the option's effect, glued with = or in the next word; the last letter of a cluster such as -lf takes the value.
+  const optionEffect = (i: number): Effect | undefined => {
+    const word = words[i]!;
+    const previous = words[i - 1]?.text ?? "";
+    const option = word.value.startsWith("-") ? (word.value.includes("=") ? word.value.slice(0, word.value.indexOf("=")) : "") : /^-[^-]/.test(previous) ? `-${previous.at(-1)}` : previous;
+    return options[option];
+  };
+  // A short option takes the rest of its word as the value: `-idata`, and `-vidata` after flags in a cluster.
+  const glued = (word: Word): { value: string; effect: Effect } | undefined => {
+    if (!/^-[^-]/.test(word.text)) return undefined;
+    const letters = [...word.text.slice(1)];
+    const at = letters.findIndex((letter) => options[`-${letter}`] !== undefined);
+    return at >= 0 && at < letters.length - 1 ? { value: word.text.slice(at + 2), effect: options[`-${letters[at]}`]! } : undefined;
+  };
+  const operandWords = words.filter((word, i) => !word.text.startsWith("-") && optionEffect(i) === undefined);
+  // With `-t DIR`, alone or in a cluster, every operand is a source and the directory is the destination. A glob expands to several words, so it may hide sources.
+  const last = operandWords.at(-1);
+  const intoDirectory =
+    spec.options?.["-t"] === "write" && words.some((word) => /^-[^-]*t/.test(word.text) || (/^--t[a-z-]*(=|$)/.test(word.text) && "--target-directory".startsWith(word.text.split("=")[0]!)));
+  const destination = spec.last && !last?.globs && !intoDirectory ? last : undefined;
+  const remote = (word: Word) => spec.remote?.test(word.value) ?? false;
+  // A copy sends what it reads only when it names another machine; a local copy keeps its reads on this one.
+  const sends = (spec.sends ?? false) && (!spec.remote || operandWords.some(remote));
+  const make = maker(home, cmd, command, walk, sends);
+  const ctx: Context = { cmd, words, walk, claimed: new Set(), make };
+  // The word list of a for loop or a [[ test is not read by the shell.
+  const operands: Effect = spec.operands ?? (program ? DEFAULT_EFFECT : "use");
+  const targets: Target[] = [];
+  for (const redirect of cmd.redirects) {
+    if ((redirect.direction === "in" || redirect.direction === "out") && redirect.target)
+      targets.push(make(redirect.target, undefined, redirect.direction === "in" ? "read" : "write", { via: "redirect", glob: redirect.globs }));
+  }
+  if (cmd.items && program) targets.push(make(cmd.items.root, undefined, operands, { via: "items", glob: false, walk: cmd.items.hidden ? "hidden" : "visible" }));
+  // xargs reads its arguments from the -a file.
+  if (cmd.wrappers.includes("xargs") && program) {
+    const options = cmd.argv.slice(0, cmd.program);
+    for (const [i, word] of options.entries()) {
+      const file = word.text === "-a" || word.text === "--arg-file" ? options[i + 1] : undefined;
+      if (file) targets.push(make(file.text, file, "read", { via: "option" }));
+      else if (word.text.startsWith("--arg-file=")) targets.push(make(word.text.slice("--arg-file=".length), word, "read", { via: "option" }));
+    }
+  }
+  if (program?.value.includes("/")) targets.push(make(program.value, program, "use", { via: "option" }));
+  const start = targets.length;
+  targets.push(...(spec.targets?.(ctx) ?? []));
+  for (const [i, word] of words.entries()) {
+    const short = ctx.claimed.has(word) ? undefined : glued(word);
+    if (short) {
+      targets.push(make(short.value, word, short.effect, { via: "option" }));
+      continue;
+    }
+    const value = pathRoles.has(word.role) && !ctx.claimed.has(word) ? operandValue(word) : undefined;
+    if (!value) continue;
+    const effect = remote(word) ? "name" : word === destination ? spec.last! : (optionEffect(i) ?? (word.role === "optarg" ? "use" : operands));
+    targets.push(make(value, word, effect, { via: word.role === "optarg" ? "option" : "operand" }));
+  }
+  const lists = spec.cwd && !targets.slice(start).some((target) => target.via === "operand");
+  if (lists) targets.push(make(cmd.cwd, undefined, "list", { via: spec.cwd! }));
+  // A program runs in its working directory, which App Data records even when the command names nothing,
+  // or when it is a program the table does not model and may read what it does not name.
+  const named = targets.some((target) => ["operand", "cwd", "scan"].includes(target.via) && !["enter", "name"].includes(target.effect));
+  if (program && !dataPrograms.includes(name) && !["cd", "pushd", "popd"].includes(name) && (!named || !specs.has(name))) targets.push(make(cmd.cwd, undefined, "enter", { via: "cwd", walk: "none" }));
+  return targets;
+}
+
+// A word that starts like a path, or touches a quote: `e.key` is a property, `'.key'` and `"cert.pem"` are files. Quotes are not paired
+// across lines, so an apostrophe in a comment does not hide the string literals after it; a string literal is a shell command that can name a file
+// anywhere in it, so its words count wherever they sit.
+function codeTokens(code: string): string[] {
+  const words = (text: string) => [...text.matchAll(/[\w.~/-]+/g)];
+  const strings = [...code.matchAll(/(['"`])((?:(?!\1)[^\n])*)\1/g)].flatMap((match) => words(match[2]!));
+  return [...words(code).filter((match) => /^[.~]|\//.test(match[0]) || /['"`]/.test(code[match.index - 1] ?? "") || /['"`]/.test(code[match.index + match[0].length] ?? "")), ...strings].map(
+    (match) => match[0],
+  );
+}
+
+export function extractTargets(req: Request): Target[] {
+  const targets: Target[] = [];
+  const add = (path: string, cwd: string, inputCwd: string, effect: Effect, options: Partial<Target>) => {
+    const input = expandHome(path, req.home);
+    targets.push({
+      path: absPath(path, cwd, req.home),
+      unresolved: input.startsWith("/") ? input : `${inputCwd}/${input}`,
+      glob: false,
+      effect,
+      walk: "none",
+      sends: false,
+      expands: false,
+      via: "tool",
+      search: false,
+      command: -1,
+      ...options,
+    });
+  };
+  const tool = (path: string, effect: Effect, options: Partial<Target> = {}) => add(path, req.cwd, req.inputCwd, effect, options);
+  if (req.operation === "read" || req.operation === "write") tool(req.pathInput, req.operation === "read" ? "read" : "write");
+  if (req.operation === "search") {
+    tool(req.pathInput || req.inputCwd, "read", { walk: "visible", search: true });
+    if (req.glob && !req.glob.startsWith("!")) tool(`${req.searchRoot}/${basename(req.glob)}`, "read", { glob: true });
+  }
+  req.commands.forEach((cmd, command) => targets.push(...commandTargets(cmd, command, req.home)));
+  // Inline code opens files the guard cannot trace, so each token that names a path is inferred to be a read target.
+  for (const { text, cwd } of req.uninspectable) for (const token of codeTokens(text)) add(token, cwd, cwd, "read", { via: "code" });
+  return targets;
+}